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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavioral nuances: it overrides Pluggy's automatic categorization, creates a persistent Category Rule affecting future transactions, and explains batch error handling ('per-item errors do not fail the whole batch'). This adds substantial context that annotations alone do not provide.

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 concise yet information-dense: three sentences covering the action, the side effect, and the batch response shape. Every sentence adds value without redundancy, and the structure flows logically from what to how to what to expect.

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?

The tool has a single parameter and no output schema, but the description includes the full return shape ('returns { updated, results: [...], errors: [...] }'), explains input semantics, and warns about the learning side effect. This makes it self-sufficient for an agent to use correctly, covering all necessary context.

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?

With 0% schema description coverage, the description compensates by fully explaining the `items` parameter structure and the provenance of its fields: 'transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories'. This gives the agent critical knowledge to invoke the tool correctly, far beyond the raw 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 function: 'Corrects the category of one or more transactions' with the specific HTTP method (PATCH /transactions/:id). It identifies the resource (transactions) and the action (correcting category), distinguishing it from sibling tools like openfinance_list_transactions or openfinance_force_sync.

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 'use this to fix miscategorized transactions and improve categorization accuracy going forward', providing clear when-to-use context. It also explains the side effect of creating a Category Rule, which is important for deciding when to invoke. However, it does not mention alternatives or explicitly state when not to use it, so it misses the full 'when-not/alternatives' criterion.

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