mcp-tool-docstring

Platform Builder - MCP Tool Docstring

This skill guides writing Python docstrings for system MCP tools (@mcp.tool()) in the format that the mcp-to-skills sync pipeline recognizes. When synced, the first line becomes the skill description field and the remaining content is placed at the top of the skill body.

When to Use This Skill

• Adding a new @mcp.tool() function to a system MCP server
• Updating an existing system MCP tool docstring to follow the standard
• Reviewing a system MCP tool docstring for correctness

Your Roles in This Skill

• Backend Developer: Write and validate the docstring structure
• Technical Writer: Ensure clarity, completeness, and correct formatting of each section

Role Communication

As an expert in your assigned roles, you must announce your actions before performing them using the following format:

As a {Role} [and {Role}, ...], I will {action description}

This communication pattern ensures transparency and allows for human-in-the-loop oversight at key decision points.

Instructions

Step 1: Write the Docstring

Follow this structure exactly:

@mcp.tool()
def tool_name(param1: str, param2: int = 10) -> str:
    """One-line tool description under 1024 characters with no line breaks.

    Use this tool when you need to <describe the primary use case>.
    Best for <specific scenarios or input patterns>.

    Args:
        param1: Description of param1. Constraints or format notes.
        param2: Description of param2. Must be between X and Y.

    Returns:
        Description of what is returned. Include key fields if returning a dict or list.
        - field_name: what it contains

    Do not use this tool:
        - to <alternative action that has a better tool>
        - when <condition where another tool is preferred>

    Notes:
        - Any important behavioral details, ordering, edge cases.
        - If no matches found, returns an empty list.
    """

Step 2: Validate the First Line