---
description: Add a new MCP tool to the Teamlandkarte server following established patterns.
---

$ARGUMENTS

## Adding a New MCP Tool

When adding a new MCP tool to `src/teamlandkarte_mcp/mcp_server.py`, follow these patterns:

### Naming Convention
- Use `verb_noun` pattern (e.g., `find_matching_capacities`, `get_task_details`, `list_open_tasks`)
- Prefix with `mcp_` in the function name for the decorator

### Required Structure
1. Define the tool function with `@mcp.tool()` decorator
2. Add clear parameter schemas with descriptions and types
3. Return Markdown-formatted output (tables for structured data)
4. Include proper error messages for invalid inputs
5. Produce deterministic outputs (same input → same output, modulo cache)

### Checklist
- [ ] Tool function defined in `mcp_server.py` with `@mcp.tool()` decorator
- [ ] Parameters have type hints and descriptions
- [ ] Output uses Markdown tables for structured data
- [ ] Error handling for invalid inputs (return helpful error messages)
- [ ] No secrets or credentials in output
- [ ] Read-only database access (never write to Trino)
- [ ] Add corresponding test in `tests/`
- [ ] Run `uv run ruff check src/ tests/` and `uv run mypy src/`
- [ ] Update `docs/assistant_system_prompt.md` with the new tool documentation

### Example Pattern
```python
@mcp.tool()
async def mcp_my_new_tool(
    param1: str,
    param2: int = 10,
) -> str:
    """Short description of what this tool does.

    Args:
        param1: Description of param1.
        param2: Description of param2 (default: 10).
    """
    # Implementation
    result = await some_operation(param1, param2)
    # Format as Markdown table
    return format_as_markdown_table(result)
```

### Security
- Never expose credentials in tool output
- Never write to the database
- Validate all inputs before processing