Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond annotations by disclosing a critical side effect: recategorization automatically creates a Category Rule that affects future transactions. It also explains batch error behavior (per-item errors do not fail the whole batch) and the exact response shape. This is rich behavioral context that annotations (readOnlyHint=false, etc.) do not capture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough but every sentence delivers value: it states the endpoint, input format, ID provenance, side effect, batch behavior, and error handling. It front-loads the core purpose ('Corrects the category...') and structures subsequent details logically. No fluff or repetition exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and no schema descriptions, the description fully compensates. It covers operation, input construction, side effects, response shape, and error handling. Given the complexity (batch processing, teaching behavior, per-item errors), the description is complete and leaves no critical ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema only defines an `items` array with two string fields, the description explains the semantic role of each field: `transaction_id` comes from openfinance_list_transactions and `category_id` from openfinance_list_categories. It also details the expected shape (array of objects with required keys) and the batch response format, adding meaning that is entirely absent from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: correcting the category of one or more transactions via PATCH /transactions/:id. It distinguishes itself from sibling list/read tools by naming the specific action and the resource it modifies, and it provides enough detail (array of transaction_id and category_id) to avoid confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool ('use this to fix miscategorized transactions') and how it improves future categorization. It also references sibling tools (openfinance_list_transactions and openfinance_list_categories) as sources for the required IDs, giving clear guidance on how to construct input and where the data comes from.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.