Tool Templates

Copy these templates to avoid syntax errors when creating MXCP tools.

Python Tool Template

Use this template for Python-based tools that require custom logic, API calls, or complex processing.

mxcp: 1
tool:
  name: YOUR_TOOL_NAME
  description: |
    Clear description of what this tool does and when to use it.
    Explain the purpose and expected behavior.
  language: python
  parameters:
    # Required parameter (no default)
    - name: required_param
      type: string
      description: "What this parameter is for"

    # Optional parameter (with null default)
    - name: optional_param
      type: string
      description: "What this optional parameter is for"
      default: null

    # Optional parameter (with specific default)
    - name: limit
      type: integer
      description: "Maximum number of results"
      default: 100
  return:
    type: object
    description: "Description of what gets returned"
    properties:
      status: { type: string, description: "Operation status" }
      data: { type: array, description: "Result data" }
  source:
    file: ../python/your_module.py
  tests:
    - name: "basic_test"
      arguments:
        - key: required_param
          value: "test_value"
      result:
        status: "success"

After copying this template:

Replace YOUR_TOOL_NAME with the actual tool name
Update the description to explain what the tool does
Update the parameters section with actual parameters
Update the return type to match expected output
Update the source.file path to point to Python module
🛑 RUN mxcp validate IMMEDIATELY 🛑

SQL Tool Template

Use this template for SQL-based tools that query databases directly.

mxcp: 1
tool:
  name: YOUR_TOOL_NAME
  description: |
    Clear description of what this SQL query does.
  parameters:
    - name: filter_value
      type: string
      description: "Filter criteria (optional)"
      default: null
  return:
    type: array
    items:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
  source:
    code: |
      SELECT
        id,
        name,
        other_column
      FROM your_table
      WHERE $filter_value IS NULL OR column = $filter_value
      ORDER BY id
      LIMIT 100
  tests:
    - name: "test_query"
      arguments: []
      # Add expected results if known

After copying this template:

Replace YOUR_TOOL_NAME with the actual tool name
Update the SQL query in source.code with actual table/columns
Update parameters section with query parameters
Update return types to match query output
🛑 RUN mxcp validate IMMEDIATELY 🛑

Resource Template

Use this template for MCP resources that provide static or dynamic data.

mxcp: 1
resource:
  name: YOUR_RESOURCE_NAME
  uri: "resource://namespace/YOUR_RESOURCE_NAME"
  description: |
    Clear description of what this resource provides.
  mimeType: "application/json"
  source:
    code: |
      SELECT
        *
      FROM your_table
      LIMIT 100

Prompt Template

Use this template for MCP prompts that provide LLM instructions.

mxcp: 1
prompt:
  name: YOUR_PROMPT_NAME
  description: |
    Clear description of what this prompt helps with.
  arguments:
    - name: context_param
      description: "Context information for the prompt"
      required: true
  messages:
    - role: user
      content: |
        Use the following context to help answer questions:
        {{ context_param }}

        Please provide detailed and accurate responses.

Validation Checklist

After creating any tool from a template:

Tool name follows naming conventions (lowercase, underscores)
Description is clear and LLM-friendly (explains what, when, why)
All parameters have descriptions
Return types are specified completely
Tests are included in the tool definition
mxcp validate passes without errors
mxcp test passes for the tool
Manual test with mxcp run tool <name> succeeds

Common Template Mistakes

Missing tool: wrapper - Always include tool: as top-level key after mxcp: 1
Using type: python - Use language: python for Python tools, not type:
Adding required: true - Don't use required: field, use default: for optional params
Empty return types - Always specify complete return types
No tests - Always include at least one test case

4.6 KiB Raw Permalink Blame History