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

Goes well past the annotations: it discloses dry-run behavior (settled_dry_run receipt, fake lsrq_dry_… settlement ref), budget decrement, that reject spends nothing and writes no receipt, and that live charging is gated. These details are consistent with destructiveHint=true, idempotentHint=true, and readOnlyHint=false, and they explain exactly what the mutation destroys or creates.

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?

Four tight sentences, front-loaded with the action and the human-confirmation framing, then descending into dry-run mechanics and idempotency. No filler and every clause carries information an agent needs before calling.

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?

There is no output schema, so the description must carry the effect story — and it does, describing receipt creation, settlement ref format, budget impact, and repeat-call behavior. For a destructive, non-open-world mutation with full annotation coverage, nothing an agent needs is missing.

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 100%, so baseline is 3, but the description adds real meaning beyond the enum text by spelling out the side effects of each decision value (approve settles, rejects spends nothing, writes no receipt). It does not explain note or proposal_id handling, so it does not fully compensate into a 5.

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 pair (approve/reject) on a specific resource (one pending proposal) and scopes it to exactly one item. This clearly separates it from propose_purchase (creates) and list_proposals (reads), so an agent can route without opening any schema.

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?

"This is the step a human should confirm" gives a clear use condition, and the approve/reject branch guidance tells the agent which input to pick for which outcome. It does not explicitly name sibling alternatives (e.g., refund_receipt for unwinding, deliver_receipt style flows), so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world. The description adds value beyond that by ruling out external side effects with Stripe or Link and by describing what is returned. It does not cover pagination or freshness, but the extra context is meaningful.

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?

A single tight sentence front-loads what is read and follows with the explicit exclusions. Every clause earns its place with no filler.

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 no-param, read-only tool with no output schema, the description is nearly sufficient: it enumerates the returned fields and rules out side effects. It could note freshness or failure modes, but an agent has enough to invoke it correctly.

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 tool takes zero parameters, so the baseline is 4. The description compensates slightly by listing the values returned in place of the absent output schema, though there is no parameter semantics to clarify.

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 (read) and resource (budget) and enumerates the returned values (amount spent, remaining, pending proposals count), which lets an agent distinguish it from the mutation siblings. It stops short of naming an alternative like set_budget explicitly, but the read scope is 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?

Provides negative guidance ('does not change the ledger, spend money, or contact Stripe or Link') that implicitly separates it from set_budget, propose_purchase, and refund_receipt, but never states when to call it or names a sibling to prefer instead. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: result ordering, inclusion of dry-run settlements and refunds, and the fact that no external calls (Stripe/Link) are made, reinforcing the closed-world hint. It omits pagination/limit behavior, which keeps it below 5.

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 short sentences, front-loaded with the core action and scope, then the disambiguating negatives. No redundant restatement of the title or name.

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 simple one-parameter read tool with full annotation coverage and no output schema, the description supplies ample scope (ordering, included record types). The only omission is return-size/pagination expectations, a minor gap rather than a blocking one.

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?

Only one parameter ('limit') and schema coverage is 100%, so the schema already documents it. The description adds nothing about the limit parameter or default result size; per the rubric, baseline 3 applies when the schema fully carries parameter meaning.

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?

Specific verb ('Read') plus resource ('receipts'), with ordering ('newest first') and content scope ('including dry-run settlements and refunds'). The closing negative clause ('Does not refund, spend money, or contact Stripe or Link') cleanly separates it from the refund_receipt sibling without the agent opening either schema.

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 explicit 'does not refund, spend money' carve-out tells the agent when to route elsewhere (refund_receipt / purchase flows), which is real routing guidance. It stops short of naming the alternative tool or stating a positive use trigger like 'use to audit past transactions', so it is clear context rather than a full when/when-not map.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description reinforces and extends this by stating the tool will not approve, reject, spend money, or contact Stripe/Link, giving concrete behavioral guardrails beyond the raw hints. It does not cover result volume or pagination, so it is good but not exhaustive.

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 short sentences with zero filler; the primary action and filter options are front-loaded and the exclusion clause follows. Every clause carries distinct information.

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 single optional enum parameter with full schema coverage and a mature annotation set, the description gives enough to invoke correctly, including the null-argument default behavior. No output schema exists but return format need not be described; only result volume/pagination is unaddressed, which is minor here.

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 100% and the single enum parameter is fully documented in the schema, including the 'pending' default. The description restates the same enum values without adding syntax, format, or edge-case meaning, so baseline 3 applies.

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 and resource ('Read purchase proposals') plus the filtering dimension ('by status'). The negative clause ('Does not approve, reject, spend money, or contact Stripe or Link') implicitly separates it from decide_proposal and propose_purchase, so an agent can distinguish it from siblings.

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?

Clearly establishes the read-vs-act context by enumerating statuses and explicitly ruling out approval, rejection, spending, and external contact, which routes the agent elsewhere for those actions. It stops short of naming the sibling tool (decide_proposal) that handles approval/rejection, so it is clear context without an explicit alternative.

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

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

With annotation coverage limited to generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description carries the real behavioral burden and does: it enumerates the negative guarantees (no money moved, no receipt, no card approval, no Stripe/Link contact), states the human-approval dependency, and discloses the over_budget edge-case behavior. This is exactly the side-effect disclosure a mutation tool needs.

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 sentences, no filler, and the strongest constraint (intent-only, no money) is front-loaded ahead of the approval dependency and the edge case. The final over_budget sentence is edge-case detail that is useful but slightly beyond the minimum, keeping it short of a 5.

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?

No output schema exists, and the description compensates by describing the observable outcome (proposal stored, over_budget set when the amount exceeds remaining budget). Combined with the safety profile and the decide_proposal hand-off, an agent has everything needed to call it correctly.

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 100%, so all five parameters are already documented in the schema and the description adds no format, range, or validation detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Record a pending purchase intent') and immediately scopes it as intent-only, sharply distinguishing it from decide_proposal, which performs the actual approval. An agent can tell it apart from its siblings without opening any schema.

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 is explicit that this records intent only and that a later human approval via decide_proposal is required before anything settles, which routes the agent to the correct next tool. It does not state an explicit when-not condition (e.g., when to skip proposing and use get_budget first), but the 'only' scoping is a clear usage boundary.

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

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

Goes well beyond the annotations: it discloses that no external call is made ('Does not contact Stripe or Link'), that the budget is restored, that the operation is once-only (reinforcing idempotentHint=true), and the exact refusal condition. Annotations cover the mutation/idempotency profile, and the description adds the missing operational context.

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?

Four short sentences, zero filler: the action is front-loaded, followed by the human-confirmation requirement and the two key behavioral constraints. 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 destructive mutation with no output schema, the description covers the essentials: what it reverses, the budget side effect, the external-call behavior, the once-only semantics, and the refusal precondition. Nothing needed to call it safely is missing.

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 100% and there are only 2 parameters, so the schema already documents receipt_id and reason. The description adds no format, constraint, or meaning for either parameter beyond what is already encoded, making the baseline 3 appropriate.

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 ('Reverse') and resource ('settled dry-run receipt') plus the resulting side effect ('restore that amount to the remaining budget'). This is clearly distinguishable from the sibling budget/proposal tools without opening any schema.

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 flags that this is 'the step a human should confirm,' which tells the agent when to pause for approval, and states the precondition ('Refuses receipts that are not settled_dry_run'). It does not name an alternative tool, but none of the siblings overlaps, so this is a clear context rather than a full routing rule.

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

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

Annotations already declare idempotentHint=true and openWorldHint=false, so the description's job is to add nuance. It does so usefully: 'Passing the same amount again does not add to the budget' clarifies that idempotency here means overwrite rather than increment, and 'Changes the ledger limit only' scopes the blast radius. It omits any permission or auth requirements, keeping it below 5.

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 sentences, front-loaded with the action and effect, then the exclusions and the idempotency caveat. Every sentence carries distinct information with no redundancy.

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 three-parameter mutation with no output schema and annotations covering the safety profile, the description covers what the tool changes, what it does not change, and repeat-call behavior. It lacks any statement of required permissions or the resulting state after the overwrite, 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 description coverage is 100%, so amount_usd, currency, and note are already documented in the schema; the baseline of 3 applies. The description adds no format, range, or unit detail beyond what the schema provides.

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 and resource ('Overwrite the local spend budget') plus the precise effect ('Changes the ledger limit only'). It is clearly distinguishable from siblings like propose_purchase and refund_receipt, which the description explicitly disclaims.

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 negation list ('Does not spend money, approve a card, settle a purchase, or contact Stripe or Link') effectively tells the agent when this tool is not the right one, which is strong routing guidance. It stops short of naming the sibling tool an agent should use instead, so it is not a full 5.

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