AIML-238: Define MCP tool naming standards and conventions

[ChrisEdwards]

Why

The MCP tool consolidation project (AIML-239) requires consistent naming standards before implementation begins. Without standardized naming conventions, consolidating 20 tools down to 12 would result in inconsistent patterns across the codebase and poor developer experience.

This establishes the foundation that all subsequent consolidation work will follow, ensuring consistency across 7 domains (Applications, Vulnerabilities, Attacks, Libraries, Route Coverage, SAST, and Prompts).

What

Created MCP_STANDARDS.md defining comprehensive naming conventions for all MCP tools in the mcp-contrast server.

Standards established:

• action_entity snake_case format for all tool names
• Verb hierarchy: search_* (flexible filtering) > list_* (scoped) > get_* (single item)
• Parameter naming: camelCase with consistent suffixes (*Id, *Name)
• Return type standards
• Documentation requirements
• Anti-patterns to avoid

Updated CLAUDE.md with MCP Tool Standards section requiring all tool development to follow MCP_STANDARDS.md.

How

Approach:

1. Analyzed existing tool naming patterns across all services
2. Identified inconsistencies and anti-patterns (mixed case, redundant words, unclear verbs)
3. Defined clear rules with decision trees for verb selection
4. Documented standard parameter names and conventions
5. Created validation checklist for tool review

Key design decisions:

• Verb hierarchy based on capability: search_* for multi-filter queries, list_* for scoped queries, get_* for single-item retrieval
• Parameter consistency: Standard names like appId, vulnId, sessionMetadataName/Value used throughout
• Filter conventions: Plural for comma-separated values (severities), singular for single values (appId)
• 64 character limit: Keeps tool names concise and readable

Step-by-Step Walkthrough

1. MCP_STANDARDS.md (103 lines)

The complete standards document with sections:

Core Convention (lines 9-27):

• Defines action_entity snake_case format
• Examples of correct and incorrect naming
• Character limits and abbreviation rules

Verb Hierarchy (lines 30-56):

• search_* - For flexible filtering with multiple optional parameters
  • Example: search_vulnerabilities(severities, statuses, appId, ...)
• list_* - For scoped lists requiring an identifier
  • Example: list_application_libraries(appId)
• get_* - For single item retrieval by ID
  • Example: get_vulnerability(vulnId, appId)

Parameters (lines 59-89):

• camelCase naming convention
• Identifier suffix patterns (*Id for UUIDs, *Name for strings)
• Standard parameter names table
• Filter conventions (plural vs singular)
• Required vs optional documentation

Checklist (lines 93-103):

• 8-item validation checklist for tool review
• Ensures compliance before code review

2. CLAUDE.md (12 lines added)

Added MCP Tool Standards section (after Architecture):

• Clear requirement: "All MCP tool development MUST follow MCP_STANDARDS.md"
• When to consult standards (creating/modifying tools)
• Quick reference to key conventions
• Links to detailed requirements

This ensures all AI agents and developers see the standards requirement prominently in project instructions.

Testing

Type: Documentation-only change

Validation approach:

• ✅ All existing tests pass (147 tests, 0 failures)
• ✅ No code modifications, only documentation added
• ✅ Spotless formatting check passes

Future validation:

• Standards will be validated during AIML-239 implementation
• Each tool consolidation PR will reference these standards
• Tool naming will be reviewed against MCP_STANDARDS.md checklist

Expected outcomes:

• Phase 1: Applications domain consolidation (5 tools → 1)
• Phase 2: Vulnerabilities domain consolidation (6 tools → 3)
• Phases 3-7: Remaining domain consolidations
• Final result: 20 tools → 12 tools with consistent naming

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com