AIML-238: Define MCP tool naming standards and conventions

CLAUDE.md

@@ -76,6 +76,18 @@ Required environment variables/arguments:
 3. **Hint Generation**: Rule-based system provides contextual security guidance
 4. **Defensive Design**: All external API calls include error handling and logging
 
+### MCP Tool Standards
+
+**All MCP tool development MUST follow the standards defined in [MCP_STANDARDS.md](./MCP_STANDARDS.md).**
+
+When creating or modifying MCP tools:
+- Read MCP_STANDARDS.md for complete naming and design standards
+- Use `action_entity` naming convention (e.g., `search_vulnerabilities`, `get_vulnerability`)
+- Follow verb hierarchy: `search_*` (flexible filtering) > `list_*` (scoped) > `get_*` (single item)
+- Use camelCase for parameters, snake_case for tool names
+- Document all tools with clear descriptions and parameter specifications
+- See MCP_STANDARDS.md for anti-patterns, examples, and detailed requirements
+
 ### Coding Standards
 
 **CLAUDE.md Principle**: Maximum conciseness to minimize token usage. Violate grammar rules for brevity. No verbose examples.
@@ -462,19 +474,22 @@ This workflow creates a standard PR ready for immediate review, targeting the `m
    - Create/apply labels: `pr-created` and `in-review`
    - Apply to all beads worked on in this branch
 
-**2. Push to remote:**
+**2. Update Jira status (if applicable):**
+   - If bead has linked Jira ticket, transition to "In Review" or equivalent review status
+
+**3. Push to remote:**
    - Push the feature branch to remote repository
 
-**3. Complete time tracking:**
+**4. Complete time tracking:**
    - Follow the **"Completing Time Tracking"** process in the Time Tracking section
    - This is for parent beads only (child beads were already rated when closed)
 
-**4. Create or update Pull Request:**
+**5. Create or update Pull Request:**
    - If PR doesn't exist, create it with base branch `main`
    - If PR exists, update the description
    - PR should be ready for review (NOT draft)
 
-**5. Generate comprehensive PR description:**
+**6. Generate comprehensive PR description:**
    - Follow the **"Creating High-Quality PR Descriptions"** section above
    - Use the standard structure: Why / What / How / Walkthrough / Testing
    - No special warnings or dependency context needed
@@ -494,14 +509,17 @@ This workflow creates a draft PR that depends on another unmerged PR (stacked br
    - **Do NOT add `in-review` label yet** (only added when promoted to ready-for-review)
    - Apply to all beads worked on in this branch
 
-**3. Push to remote:**
+**3. Update Jira status (if applicable):**
+   - If bead has linked Jira ticket, keep status as "In Progress" (draft PR, not ready for review yet)
+
+**4. Push to remote:**
    - Push the feature branch: `git push -u origin <branch-name>`
 
-**4. Complete time tracking:**
+**5. Complete time tracking:**
    - Follow the **"Completing Time Tracking"** process in the Time Tracking section
    - This is for parent beads only (child beads were already rated when closed)
 
-**5. Create DRAFT Pull Request:**
+**6. Create DRAFT Pull Request:**
    - **Base branch**: Set to the parent PR's branch (NOT main)
    - **Status**: MUST be draft
    - **Title**: Include `[STACKED]` indicator
@@ -524,7 +542,7 @@ This workflow creates a draft PR that depends on another unmerged PR (stacked br
    - After the warning and dependency context, follow the **"Creating High-Quality PR Descriptions"** section
    - Use the standard structure: Why / What / How / Walkthrough / Testing
 
-**6. Verify configuration:**
+**7. Verify configuration:**
    - Confirm PR is in draft status
    - Confirm base branch is the parent PR's branch
    - Confirm warning and dependency context are prominently displayed

MCP_STANDARDS.md

@@ -0,0 +1,103 @@
+# MCP Tool Naming Standards
+
+**Version:** 1.0
+**JIRA:** AIML-238
+**Created:** 2025-11-18
+
+---
+
+## Core Convention: `action_entity`
+
+Tool names (in `@Tool` annotation) use `action_entity` snake_case format.
+
+**Format:**
+- Action verb: `search`, `list`, or `get`
+- Entity: what's operated on
+- Separator: single underscore
+- Casing: lowercase throughout
+
+**Examples:**
+- ✅ `search_vulnerabilities`, `get_vulnerability`, `list_application_libraries`
+- ❌ `list_Scan_Project`, `get_ADR_Protect_Rules`, `listApplications`
+
+**Limits:**
+- 64 character max
+- No redundant words ("all", "data")
+- Abbreviate only when widely known (cve, id)
+
+---
+
+## Verb Hierarchy
+
+### `search_*` - Flexible Filtering
+- Multiple optional filters
+- Paginated results
+- Returns items matching filter combinations
+- Use when: "find all X where..."
+
+**Example:** `search_vulnerabilities` with optional appId, severities, statuses, etc.
+
+### `list_*` - Scoped Lists
+- Returns all items in a scope
+- Requires scope identifier (appId, projectName)
+- Minimal filtering
+- Use when: "show all X for Y"
+
+**Example:** `list_application_libraries(appId)` - all libs for one app
+
+### `get_*` - Single Item
+- Fetches one item by identifier
+- Required identifier(s)
+- Returns single object
+- Throws if not found
+- Use when: "get details of X"
+
+**Example:** `get_vulnerability(vulnId, appId)` - one specific vuln
+
+---
+
+## Parameters
+
+### Naming: camelCase
+- ✅ `appId`, `vulnId`, `sessionMetadataName`
+- ❌ `app_id`, `session_Metadata_Name`
+
+### Identifier Suffixes
+- `*Id` - UUID/numeric: `appId`, `vulnId`, `attackId`
+- `*Name` - string: `projectName`, `metadataName`
+- Never: `*ID` (caps) or `*_id` (snake_case)
+
+### Standard Names
+
+| Parameter | Usage |
+|-----------|-------|
+| `appId` | Application identifier |
+| `vulnId` | Vulnerability identifier |
+| `cveId` | CVE identifier |
+| `sessionMetadataName/Value` | Session metadata |
+| `page` / `pageSize` | Pagination (1-based) |
+| `useLatestSession` | Latest session flag |
+
+### Filter Conventions
+- **Plural** for comma-separated: `severities`, `statuses`, `environments`
+- **Singular** for single values: `appId`, `keyword`, `sort`
+
+### Required vs Optional
+- `@NonNull` - required
+- `@Nullable` - optional
+- Document dependencies: "sessionMetadataValue (required if sessionMetadataName provided)"
+
+
+---
+
+## Checklist
+
+- [ ] `action_entity` snake_case format
+- [ ] Verb matches capability (search/list/get)
+- [ ] Entity clear and unabbreviated
+- [ ] Parameters camelCase and consistent
+- [ ] Return type follows standards
+- [ ] @Tool description clear and concise
+- [ ] Required vs optional documented
+- [ ] No redundant words
+