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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is covered. The description adds the context that it accepts 'exactly specified fields', which is more about the input interface than behavioral side effects. It does not disclose whether the operation is idempotent, how it handles validation, or what happens on success/failure. Given the annotations cover the safety profile, a 3 is appropriate for adding limited behavioral context beyond the structured metadata.

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 two sentences with no filler. The first sentence front-loads the purpose and the condition for use, and the second sentence provides a crucial pointer for ID sourcing. Every word earns its place, making it both concise and efficiently structured for quick agent comprehension.

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 9 parameters, 3 required, and an output schema exists. The description covers the purpose and hints at ID sourcing, but it does not elaborate on the interplay of parameters (e.g., toAccountId only for transfers, date defaulting to today). While the schema itself documents some of these, the description could have highlighted the transfer-specific parameter or the validation constraints. For a moderately complex tool, the description is adequate but leaves the agent to infer several usage details from the schema.

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?

Schema description coverage is 56%, meaning about half the parameters have descriptions in the schema. The description only adds a hint that account/category IDs come from list_accounts and list_categories, which is useful but does not explain the semantics of other parameters like date, note, merchant, tagIds, or toAccountId. With moderate coverage, the description should compensate for the missing parameter documentation, but it does not. It adds marginal value over the schema but does not fully fill the gap.

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 states a specific verb ('saves') and resource ('transaction'), and immediately clarifies the distinguishing use case ('for cases where phrase parsing does not fit'). This clearly separates it from the sibling quick_add, which likely handles phrase parsing. The mention of account/category IDs from list tools adds concrete context about the input sources, making the tool's purpose unambiguous.

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 indicates when to use this tool: when phrase parsing does not fit. This implies an alternative (likely quick_add) without naming it directly. It also gives a practical hint to source IDs from list_accounts and list_categories. However, it does not explicitly state when NOT to use it or mention other alternatives (e.g., update_transaction for edits), so it stops short of a full usage guideline.

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