budget_settle

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

Adds two things annotations don't carry: an authorization requirement ('Requires manage scope') and the mechanism behind idempotency ('Safe to retry with the same request_id'), which is more actionable than the bare idempotentHint. It doesn't describe what early settlement changes in downstream state or whether it can be undone with budget_reverse, leaving some behavioral gaps.

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?

Three short clauses, no filler, with the scope prerequisite front-loaded before the usage note and the retry guarantee. Every sentence carries information an agent needs.

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 two-parameter mutation with no output schema, the description covers authorization, the default server behavior, and retry semantics. Missing only the date format/selection detail and any hint of the response, which keeps it from a 5.

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 coverage is 0%, so the description must document both parameters. It effectively explains request_id as an idempotency key that must be reused on retry, but the `date` parameter is never mentioned — no indication it selects which day to settle, nor its expected format. Half the parameters remain unexplained.

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?

States a specific verb ('settle') and object ('a day'), clarified by the note that automatic settlement exists server-side, which distinguishes it from passive siblings like budget_status or budget_schedule. It never names the domain object being settled (budget/day ledger) or names a sibling alternative, so it stops short of a 5.

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?

'Explicitly settle a day early; automatic settlement already runs on the server' gives a clear condition for use: only when you want to force settlement before the automatic run. The when-not is implied rather than stated, and no sibling tool (e.g., budget_reconcile) is named as the alternative for ordinary reconciliation, so it is clear context without explicit exclusions.

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