Skip to content

Pseudo-function style in MCP tool descriptions #5291

@MarkusNeusinger

Description

@MarkusNeusinger

Follow-up to the frontend pseudo-function style pass on branch claude/consistent-pseudo-function-style-G5I1a. The style guide (docs/reference/style-guide.md §7.4.1) codifies subject.verb(). MCP tool names in api/mcp/server.py follow Python snake_case (list_specs, get_spec_detail, ...) and can't contain dots, so the tool names themselves must stay as-is.

Proposal

Keep the tool names unchanged (public contract) but add the pseudo-function alias to each tool's docstring / description so it appears in AI-assistant tool listings. Example:

@mcp.tool()
def list_specs(...) -> ...:
    """List all specs in the catalog. (Exposed as `specs.list()` in the anyplot MCP vocabulary.)"""

Suggested mapping:

Python tool Vocabulary alias
list_specs specs.list()
search_specs_by_tags specs.search()
get_spec_detail spec.detail()
get_implementation impl.get()
list_libraries libs.list()
get_tag_values tags.values()

Risks

  • No breaking change — tool names remain the same, just docstring additions.
  • Possible AI confusion: an assistant reading "Exposed as specs.list()" might try to invoke specs.list as a tool. Mitigation: make the phrasing explicitly descriptive ("documented as", not "also callable as") and keep the real tool name as the first word of the docstring.
  • Docs sync: if there's a separate docs/reference/mcp.md, it needs the aliases too.

Scope suggestion

One PR touching api/mcp/server.py docstrings + any MCP reference docs. Low risk, mostly cosmetic.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions