Skip to main content

Overview

Every tool is a Python async function decorated with @tool. The decorator auto-generates the Claude API tool schema from the function signature and docstring.

Step 1: Choose the right file


Step 2: Write the tool

Rules:
  • Always scope queries to user_id — never fetch data without it
  • Return a dict — Claude will receive it as JSON
  • No default values in the function signature for required parameters (causes schema issues)
  • Keep tool names snake_case and globally unique

Step 3: Register the tool

In the relevant domain specialist file (backend/orchestrator/specialist.py), add your tool to the domain’s tool list:

Step 4: Add a loading label (Flutter)

In lib/features/ai_agent/providers/chat_provider.dart, add your tool name to the _toolLabels map:

Step 5: Test

Or call the endpoint directly: