defrr

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

Goes beyond the annotations by disclosing the credit cost (2 credits, refunded on failure) and the concrete accounting effect: closed-month revenue is reversed, open periods are removed. The only tension is that 'removes the rest' reads destructive while destructiveHint=false; this is plausibly an accounting reversal rather than a hard delete, so it is not a clear contradiction but leaves some ambiguity.

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: usage trigger first, then effect, then cost. Every sentence carries distinct information with no repetition of the title or schema.

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 nested mutation with no output schema, the description covers trigger, reversibility scope and cost. It does not state what the call returns or how the closed-month correction appears afterwards, which is a minor remaining gap.

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 every parameter, including nested term fields and lockedThrough, is documented in the schema. The description adds no parameter-level detail beyond the schema, so the 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 action and scope: voiding and refunding a whole contract, reversing recognised revenue and removing the remainder. It implicitly separates itself from defrr_cancel_renewal by specifying 'whole contract', but never names that sibling, so the differentiation requires inference.

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?

'Use when a whole contract is voided and refunded' gives a clear triggering condition. However, it offers no explicit exclusion against defrr_cancel_renewal or defrr_reprice_contract, which are the closest alternatives an agent would weigh.

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?

The description adds meaningful behavior beyond the annotations: it says the tool returns the credit note, reversal for closed months, and month-by-month revenue, and that the operation costs 2 credits with refund on failure. It does not fully explain the mutation's side effects or permissions, but the cost/refund and return-content disclosures are valuable.

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 compact and front-loads the usage condition, then follows with return contents and cost. It earns its space, though the first sentence is awkwardly phrased and could more directly state the action.

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 complex mutation with nested contract terms and no output schema, the description helpfully explains what is returned and the credit cost. However, the ambiguity about whether the tool performs cancellation or reports an already-cancelled renewal leaves a notable contextual gap.

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 the nested schedule, termIndex, and lockedThrough parameters are already well documented in the schema. The description does not add parameter-specific semantics beyond the schema's own detail, which is appropriate baseline behavior.

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 identifies the resource ('the latest renewal') and refund scope, but its opening phrase 'Use when the latest renewal is cancelled...' sounds like a condition rather than clearly stating that this tool performs the cancellation. The name and title help, yet the description alone leaves the action somewhat ambiguous, especially versus a query or the sibling defrr_cancel_contract.

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 gives one usage trigger ('when the latest renewal is cancelled and refunded in full') and implies only the latest renewal is eligible, but it does not name alternatives such as defrr_cancel_contract or defrr_reprice_renewal, nor does it state when not to use this tool.

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: states nothing is corrected, credited or saved, that the call costs 1 credit (refunded on failure), and describes the returned monthly billing/revenue/deferred balance and totals. The non-read-only annotation is explained indirectly by the credit charge, though the 'create' name versus 'nothing saved' framing creates mild framing tension rather than a true contradiction.

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?

Front-loaded with the triggering condition and the no-persistence scope before any edge cases, and virtually every sentence carries operational content. It is dense, however, and the parenthetical about foreign currency / single-term quantity of 1 / renewals packs three caveats into one hard-to-parse clause.

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 four-parameter tool with a nested terms array and no output schema, the description covers trigger, side effects, cost, currency handling, back-dated behaviour, and return values. An agent has enough to decide whether to call it and how, and to reason about the response shape without an output 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 coverage is 100%, so the baseline is 3; the description earns credit by adding relational meaning the schema cannot, notably that exchangeRate is required with currency and quoted as base-currency-per-one-unit, and by spelling out the lockedThrough catch-up effect on the schedule. It does not add much on the nested term fields themselves, which the schema already documents fully.

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 opening sentence gives a specific verb and resource ('work out revenue and billing schedule from the terms') plus a crucial scope qualifier ('without saving it anywhere'). It also names the sibling it is not (defrr_save_contract), so an agent can separate this from cancel/reprice/process_renewal 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?

Explicit trigger ('Use when a new deal is signed...'), explicit exclusion of persistence, and a named alternative ('to record the contract in the user's defrr organization, use defrr_save_contract instead'). It additionally gives conditional guidance for foreign-currency deals and back-dated contracts, which is exactly the when-to-use detail an agent needs.

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 only say non-readOnly, non-idempotent, non-destructive; the description adds the materially important traits: all-or-nothing atomicity ('if one contract is rejected the call fails and nothing is charged'), cost of 1 credit per contract with refund on failure, and that nothing sent is stored. It also spells out the arithmetic identity of each month's output and the carry/grandTotal handoff across batches.

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?

Front-loaded with purpose and return value, then constraints, then batching. It is a single dense block with several clauses per sentence, but nearly every clause carries non-obvious information (atomicity, credits, no storage, batch carry), so little is wasted.

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 fully by describing the per-month billing/revenue/ending-deferred fields and the grandTotal, plus the batch carry protocol. Combined with the deep nested schema, an agent has everything needed to call this correctly on both small and large sets.

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; the description goes further by explaining the ordered batch protocol and the exactly-as-given carry contract across calls, which the schema alone only hints at. It does not cover the 'shape' enum (wide vs rows) in prose, leaving that entirely to the 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?

Opens with a specific verb+resource ('deferred revenue roll-forward for a set of contracts') and states exactly what comes back. It also anchors itself to the sibling defrr_create_contract ('Each contract is built like defrr_create_contract'), so an agent can distinguish the batch case from the single-contract case immediately.

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?

Explicit trigger ('Use when you need the deferred revenue roll-forward for a set of contracts'), an explicit alternative for very large sets (call the REST API from a script instead of through the model), and the batching protocol when exceeding 50. Nothing is left to inference.

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 and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by noting the operation is 'Free' and should be used before a calculation.

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 purpose and followed by the key cost detail. Every sentence adds useful information with no waste.

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 zero-parameter, read-only balance check with no output schema, the description gives enough context: what it returns, when to use it, and that it is free.

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?

There are zero parameters, so schema coverage is complete by default and the description does not need to explain parameter meanings. Baseline 4 applies for a no-parameter tool.

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 clear verb and resource: 'see how many credits the account has left.' It is easy to distinguish from the contract/renewal siblings, though it does not explicitly name alternatives or exclusions.

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 gives a clear usage context: check before running a calculation. No when-not-to-use guidance or alternatives are provided, but the intended timing is explicit.

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 by disclosing batch limits (50 per call), per-call credit cost with refund on failure, that supplied data is not retained, and the posting rule when lockedThrough is set (billing and catch-up revenue move to the first open month). These are non-obvious operational traits an agent cannot infer from readOnly/destructive/idempotent hints.

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?

Front-loaded with the trigger and the required inputs, then the return shape, then edge-case behavior — a sensible ordering with little waste. The return-value sentence is a long multi-clause run (price comparison total and per month, billing entry, schedule, monthly totals) that would read better as a list, but no sentence is 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?

With no output schema and only two top-level parameters, the description carries the burden well: it enumerates what comes back (renewal term, price comparison total and per month, billing entry, revised schedule, monthly totals) and explains the locked-month posting rule. An agent has enough to call it and interpret the result without opening anything else.

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% and the nested field descriptions (endDateIncluded, priceForRenewalTerm vs. term price, exchangeRate) are already detailed in the schema. The description restates the input contract at a high level ("send each contract's terms as they stand") without adding semantics beyond what the schema documents, so the baseline 3 applies. The lockedThrough behavior it describes is genuinely added value, but it is framed as posting behavior rather than 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?

States a specific verb and resource up front ("Use when customers renew and you need the renewal worked out") and immediately names the inputs (contract terms, renewal end date, renewal price) and outputs. It also differentiates from a sibling by routing contracts on a different recognition basis to defrr_create_contract.

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?

Gives a clear activation trigger ("when customers renew and you need the renewal worked out") and an explicit exclusion with the alternative tool ("a different basis is a new contract (defrr_create_contract)"). It does not distinguish itself from defrr_reprice_renewal or defrr_cancel_renewal, which are the closest-sounding siblings an agent might confuse it with.

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?

Adds real context beyond the annotations: it discloses outputs (credit note, revenue to reverse for closed months, corrected revenue by month) and a cost model ('2 credits, refunded if it fails'). What it omits is that idempotentHint=false means repeat calls compound credits, and there is no statement about whether the credit can be undone.

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 with no filler: scope first, exclusion second, return values third, cost last. Every sentence carries information an agent needs before invoking.

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, but the description names what comes back, and it hints at the lockedThrough posting mechanism. The remaining gap is the non-idempotent mutation risk, which matters for a tool that issues credits.

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 three parameters including the nested schedule are already fully documented, and the description adds only the framing that renewals carry their own prices. That is the baseline-3 case where the schema does the semantic work.

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 (reprice the contract's ORIGINAL term for a credit) and explicitly bounds the scope: renewals keep their own prices. An agent can distinguish it from defrr_reprice_renewal without 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?

Gives both the when ('original term was priced too high and needs a credit') and the when-not with a named alternative ('to correct a renewal use defrr_reprice_renewal'). The routing is unambiguous.

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?

The description provides critical behavioral context beyond the annotations or schema. It discloses the operational cost (2 credits) and a recovery mechanism (refund if it fails), which are essential for risk-aware agent behavior. It also details the multi-part return structure (credit note, reversals, corrected revenue).

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 definition is highly concise. The most critical information—the use case, output, and transaction cost—is packed into two sentences, front-loading the utility and risks.

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 the complexity of the input schedule and the transactional nature of the tool, the description is remarkably complete. It addresses the required inputs, the cost/risk (2 credits), and the detailed output, making it robust even without a specific output schema provided.

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 100% schema coverage, the baseline is 3. The description confirms the necessity of a reduced price but does not add semantic meaning to the parameters themselves that isn't already documented in the detailed input 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 purpose is extremely clear, defining the specific scenario: when a renewal was priced too high and requires a credit. By focusing on 'renewal' and the 'credit' necessity, it effectively differentiates itself from sibling tools like defrr_reprice_contract.

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 provides explicit usage criteria by stating the exact problem it solves ('priced too high and needs a credit'). This eliminates ambiguity and directs the agent immediately to this tool over general repricing or cancellation tools.

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?

The description details critical behavioral traits not found in the schema or standard annotations, such as the credit cost per line ('Costs 1 credit per line'), the data retention policy ('Nothing you send is stored'), and the specific calculation methodology for hybrid lines.

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 very long due to the inherent complexity of the tool's logic, but it is well-structured. Every sentence provides necessary functional context rather than padding.

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 definition is exhaustively complete for such a complex financial tool. It covers input expectations, calculation cycles, credit usage, and output behavior, leaving almost no ambiguity for the AI agent.

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?

Given the complexity, the description goes beyond the schema by explaining the logic of the inputs. It clarifies concepts like how tiers function ('Tiers price band by band') and the difference between usage quantities (not running totals).

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 defines the tool's purpose: to convert customer usage into monetary costs month by month. It also identifies the four specific pricing models it supports (flat, volume, prepaid, hybrid).

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 provides detailed instructions on when and how to use the tool based on the billing cycle. It contrasts standard monthly usage (without startDate) against contract-based, anniversary cycles (with startDate), which is crucial for correct invocation.

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