Edit Expense

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

With no annotations, the description carries the behavioral burden, and it does disclose the key non-obvious behavior: only provided fields are updated, so omitted fields remain untouched. It does not mention invalid-ID errors or permissions, but for an edit tool with an output schema the core mutation semantics are communicated.

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?

Two concise sentences, no filler, and the most important behavioral rule is front-loaded second. Every word earns its place, and it is easy to scan while still being specific.

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?

Given 9 parameters, 100% schema coverage, and an output schema, the description is sufficiently complete for making a correct call. It could mention what happens if expense_id does not exist, but that is margin error-handling detail rather than a missing usage requirement.

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?

The schema already documents all 9 parameters, including default sentinel semantics like 'Pass 0 to keep current' and 'Pass None to keep current.' The description adds no new parameter-level detail beyond the partial-update rule, so schema coverage does the heavy lifting and this stays at baseline.

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 edits an existing expense, which immediately separates it from add/list/delete/search siblings. The 'existing' qualifier also signals that this is a mutation of an already-created expense, and the sentence is action-first rather than tautological.

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?

It tells the agent to use this tool when modifying an existing expense, and the partial-update note implicitly says 'do not pass fields you don't want changed.' However, it does not name alternatives or explicitly state when not to use it, so it is clear context but lacks exclusions.

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