Tool Metadata Example

This example demonstrates how to use tool metadata to describe your tools' classification, behavior, and custom properties.

What is Tool Metadata?

Tool metadata provides structured information about what a tool does:

Field	Purpose	Used For
Classification	What type of service the tool interfaces with	Tool discovery & selection boosting
Behavior	What effects the tool has	Policy decisions, MCP annotations
Extras	Arbitrary key/values	Custom logic (routing, rate limits, etc.)

Classification

Describes what type of service the tool interfaces with.

classification=Classification(
    service_domains=[ServiceDomain.EMAIL],  # What type of service?
)

Service Domains (what type of service): EMAIL, CRM, MESSAGING, DOCUMENTS, CLOUD_STORAGE, SOURCE_CODE, PAYMENTS, SOCIAL_MEDIA, etc.

For tools with no external service (open_world=False), classification is None.

Behavior

Describes the tool's effects and maps to MCP annotations.

behavior=Behavior(
    operations=[Operation.CREATE],  # What effect? READ, CREATE, UPDATE, DELETE, OPAQUE
    read_only=False,                # Does it only read data?
    destructive=False,              # Can it cause irreversible data loss?
    idempotent=True,                # Are repeated calls safe?
    open_world=False,               # Does it interact with external systems?
)

These values become MCP annotations that clients like Claude can use to make informed decisions.

Extras

Arbitrary key/values for custom logic that don't affect tool selection.

extras={
    "billing_tier": "free",
    "max_requests_per_minute": 100,
    "data_classification": "internal",
}

Use extras for: IDP routing, feature flags, rate limiting hints, compliance metadata.

Running the Example

cd examples/mcp_servers/tool_metadata

# Install dependencies
uv sync

# Run with stdio transport
uv run src/tool_metadata/server.py stdio

# Or run with HTTP transport
uv run src/tool_metadata/server.py http

Tools in This Example

Tool	Operations	Behavior	Notes
`reverse_text`	READ	read_only, idempotent	Pure computation
`search_notes`	READ	read_only, idempotent	Query data
`create_note`	CREATE	not idempotent	Creates new data
`update_note`	UPDATE	idempotent	Modifies existing data
`delete_note`	DELETE	destructive, idempotent	Removes data permanently
`get_notes_stats`	READ	read_only	Has `extras` for custom metadata
`upsert_note`	CREATE, UPDATE	idempotent	Multi-operation compound action

2.7 KiB Raw Blame History