84 lines
2.7 KiB
Markdown
84 lines
2.7 KiB
Markdown
# 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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
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 |
|