aurgus

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

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses important behavior: the report is deterministic, composed from a fixed semantic layer with no raw SQL, tied to the ledger, and accrued uses the same earned formula as the money path. It also states the required connected account and that it returns grouped rows plus a total.

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 front-loaded with the core action and key parameter meanings, and most sentences carry useful information. It is somewhat dense and uses emphasis-heavy formatting, but it is not padded with irrelevant material.

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 tool with no output schema, it explains the return shape at a high level: grouped rows plus total. It also covers determinism, read-only behavior, semantic-layer constraints, and authentication. Remaining gaps are minor, such as ordering, pagination, or the exact composition of the total.

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 schema already documents all four parameters and both enums. The description reinforces the enum meanings and adds the ledger-consistency note for 'accrued', but most parameter information is already present in 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?

The description states a specific verb and resource: build a governed analytics report over rebate data, with fixed measures and group-by dimensions. It clearly distinguishes itself from raw SQL by emphasizing the semantic layer, but it does not explicitly differentiate itself from siblings such as report, run_report, or list_reports.

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 condition with examples: use when the user asks to see, analyze, or break down their rebates. It also states the account prerequisite, but it does not describe when not to use this tool or point to alternative report-related 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?

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavioral context: greetings are free, real runs require a connected account, and Aurgus reads engagement state and returns a single next step. It also discloses that the tool asks rather than assumes on direction. It stops short of describing latency, cost, or what a non-connected-account response looks like.

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 core rule and the routing exclusion; every clause carries information. It is on the long side and the parenthetical example list plus the repeated 'single next step' framing could be tightened, but there is 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 7-optional-parameter conversational dispatcher with no output schema, the description supplies what's missing: entry criteria, parameter timing, the auth precondition, the shape of the reply (state read + one next step), and the handoff relationship to specialized tools. Nothing an agent needs in order to call it correctly is absent.

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 schema already documents all seven fields, including the direction enum-in-prose. The description adds timing guidance ('Pass entity/period/program when the user has named them ... engagement_id once one is open'), which is real value, but it does not touch `who_certifies` or `direction`, leaving partial coverage in prose terms.

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?

Names a concrete resource (Aurgus, the client's revenue-management controller) and a concrete action (relay the user's message to it), then explicitly distinguishes itself from the 30+ specialized siblings: 'the specialized tools ... are the controller's hands — reach for one only when Aurgus's reply tells you to.' An agent can pick between this and `ingest`/`compute_close`/`sign_close` without opening a 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 an explicit positive rule ('For ANYTHING the user says to Aurgus ... call THIS'), concrete triggering examples ('a greeting, close Q3, where are we'), and an explicit exclusion rule for the specialized tools with the condition that selects them (only when Aurgus's reply directs it). When-to-use, when-not, and alternatives are all covered.

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 readOnly/destructive annotations: it discloses there is no cost, no account/auth required, and no computation performed, and it describes the observable behavior (Aurgus introduces itself and leads with questions about client, period, and close scope). That is exactly the context an agent needs to predict what the call produces without an output schema.

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 trigger condition is front-loaded in the first clause, and the rest flows logically from triggers to behavior to next step. The quoted utterance list is somewhat long and partly redundant ('hello', 'hey Aurgus' alongside the general rule), but it earns most of its space as the disambiguating signal for a greeting tool.

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, yet the description covers what happens on the call, what it does not do (no computation, no fees, no account), and where to go next. For a zero-required-parameter entry-point tool, nothing an agent needs to invoke it correctly 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?

There is a single optional parameter and schema coverage is 100%, with the schema already explaining that 'scenario' is what the user wants to close and that it gets woven into the greeting. The description does not add any further guidance on how to populate or omit 'scenario', so it sits at the 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?

States a specific action (greet/introduce Aurgus and kick off the engagement) and what the tool actually does internally: introduces Aurgus as an independent revenue-management controller, asks for client/period/close scope. It also names the sibling it hands off to (open_engagement), so an agent can distinguish it from the actual open flow without inspecting schemas.

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 explicit trigger conditions ('the moment the user greets Aurgus or wants to start') reinforced by concrete example utterances spanning greetings and intent statements. It also states the boundary of its role — it computes nothing and the next step is open_engagement — which routes the agent forward rather than leaving the handoff implicit.

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?

Discloses the behavior annotations omit: it posts a final true-up Adjustment that moves money, resolves the open balance to $0, then freezes the agreement so no future transactions calculate against it, and requires the account to be connected. The 'Terminal' label and the dry-run-first requirement give the agent the irreversibility profile that readOnlyHint=false/destructiveHint=false alone do not convey.

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 action and the terminal warning, then exclusions, then the call protocol, then requirements. Slightly long and heavy on capitalization for emphasis, but each sentence carries distinct information rather than repeating the 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 money-moving terminal mutation with no output schema, the description covers what changes (open balance to $0, status to 'closed'), what happens afterward (no further calculations), how to preview it safely, and what is required. Nothing an agent needs before calling 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; the description adds value by framing confirm as a two-step dry-run-then-post protocol and naming agreement_id as a hard requirement ('Needs the agreement_id'). It does not explain force or reason, which the schema already covers.

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 (close an agreement) and pins the scope as terminal: 'the terminal true-up at the END of its life'. It explicitly disclaims the two nearest siblings, compute_close and settlement, so an agent can separate it from the periodic run 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 an explicit when-not ('This is NOT the periodic run (compute_close) or the periodic payout (settlement)'), a prerequisite (connected Aurgus account), and an exact call protocol: dry-run without confirm first, then re-call with confirm:true. 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?

Goes well beyond readOnlyHint=false: it states terms are PROPOSED not PARSED, that nothing is created on draft, that finalize stages for a human approver, and that the caller cannot self-approve. These are critical behavioral traits an agent would otherwise guess wrong.

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 core action and the draft/not-created caveat, and every sentence carries weight. Slightly heavy with capitalized emphasis that could be trimmed, but the density is justified by the multi-turn protocol it must convey.

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, yet the description fully explains the conversational loop, what is returned (drafted terms + follow-up questions), and the staging/approval outcome. An agent has everything needed to invoke it correctly across turns.

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, but the description adds real meaning: finalize should be true only after review, proposal must be echoed verbatim from a prior call, and clarifications resolve follow-ups. This clarifies the multi-turn protocol beyond what the field-level schema states.

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+resource ('Build a rebate/incentive agreement by talking it through') and immediately distinguishes it from its nearest sibling (ingest_agreement). An agent can tell exactly what this tool produces — a drafted proposal, not a created record — without opening the 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 names when to use it (no document, ASC 606 step 1, before transaction data) and when not to (when a document exists, prefer ingest_agreement with its deterministic parser). It also explains the two-turn draft→finalize loop, so the agent knows the sequencing.

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: refuses when no engagement is open and routes back to open_engagement, requires a connected Aurgus account, and clarifies that nothing posts to the GL. Two gaps remain: readOnlyHint=false is not explained (presumably the computed result is persisted inside the engagement), and there is no statement about re-running (idempotency / whether a second call overwrites the prior computed close).

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 core identity ('The RUN step (step 6)…') followed by the anti-pattern warning, prerequisites, return content, and side-effect note in a logical order. It is on the long side for a zero-parameter tool, but each sentence 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?

With no output schema, the description usefully previews the return ('the number, how earned / claimed / credited line up, and any flag worth raising'). Combined with prerequisites, refusal behavior, GL non-posting, and the auth requirement, an agent has everything needed to call it correctly and interpret the result.

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 and the schema coverage is 100%, so nothing needs documenting. The description correctly implies the tool derives its input implicitly from the open engagement state rather than from arguments.

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 — 'The RUN step (step 6) of an open engagement' that works the earned → settled → open accrual across active agreements and certified data. The domain scoping ('earned → settled → open accrual', 'active agreements', 'certified data') clearly separates it from siblings like compute_commission, compute_lease, compute_trade_spend, and recalculate.

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 names the wrong first move ('Do NOT call this as the first thing when a user says compute the close'), enumerates the required prerequisite chain (open_engagement → establish agreement → request + certify data → run), and states the fallback behavior when no engagement is open. The alternative (open_engagement) and the condition selecting it are both given.

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 declare readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does it well: it discloses the computation sequence (classify → capitalize → straight-line amortize), the refusal/ask behavior on unclear recoverability, the side effect that 'the result is recorded on the engagement file', and the downstream principal sign-off before workpapers are delivered. The parameter-level notes on termination triggering an ASC 340-40-35-3 impairment open item add further non-obvious behavior.

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 standard reference, then the required inputs, then behavior and outputs. Dense but nearly every clause carries information; the closing workflow sentence about the engagement file and principal sign-off is useful context rather than filler, though the description is on the long side for a single computation tool.

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, yet the description enumerates the return values (capitalized asset, amortization to date, period expense, net carrying amount) and the impairment open-item path. For an 8-parameter mutation tool with no output schema, this covers what an agent needs to call it correctly and interpret the result.

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 baseline is 3, but the description adds meaning beyond the schema by explaining the amortization mechanics — straight-line over the benefit period with elapsed months driving amortization to date — which tells the agent how benefit_months and months_elapsed interact. It also frames the output set (capitalized asset, amortization to date, period expense, net carrying amount) that the parameters feed.

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 ('Compute a sales-commission engagement') and pins it to a named standard (ASC 340-40, incremental cost to obtain a contract). It explicitly separates itself from the neighbouring revenue tool: 'This is a capitalized asset and an amortization schedule, NOT revenue.' An agent can distinguish it from compute_revenue_contract 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 the inputs needed to invoke it ('Give the commission amount, the benefit period it amortizes over, and how many months have elapsed') and states the refusal condition ('It refuses (asks) if recoverability or the amount is unclear'). It does not name sibling tools such as compute_close or compute_lease as alternatives, so routing is inferred from the 'NOT revenue' exclusion rather than stated outright.

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 declare it is a non-read-only, non-destructive write; the description goes far beyond that by disclosing the full workflow: results are recorded on the engagement file, a principal signs before workpapers are delivered, and ungrounded inputs become OPEN ITEMS rather than guesses. It also states the tool is interactive (it will ask for a missing rate), which an agent needs to know before calling.

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?

Purpose is front-loaded in the first clause, followed by inputs, outputs, and edge-case handling in a logical order. It is dense and long, but nearly every clause carries operative information (citation references, exclusion rules, open-item behavior) rather than 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 an 11-parameter, no-output-schema tool with minimal annotations, the description supplies what is otherwise missing: it names the three computed outputs (liability, ROU asset, amortization schedule), explains the two classification paths, and clarifies how it handles ungroundable inputs. An agent has everything needed to call it correctly and to anticipate the response shape.

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, but the description adds genuine meaning by linking parameters to the accounting model — ROU asset = liability + initial direct costs − incentives, and usage-based variable payments excluded from the liability under 842-10-30-6. The 'never assumes a rate' note on the discount rate is a real semantic constraint beyond the schema text.

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 — measure a lease under ASC 842 — and immediately scopes it to the lessee side for real estate and equipment. This is unmistakably distinct from siblings like compute_revenue_contract, compute_commission, or compute_close, which cover different accounting domains.

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 clear preconditions (term, CERTIFIED discount rate, payment schedule) and an explicit exclusion (lessor accounting deferred to v2), plus the behavioral rule that a missing rate triggers a question rather than an assumption. It stops short of naming a sibling alternative for adjacent tasks, but the scope boundaries are 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?

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds meaningful behavior: the engine logs undetermined matters as OPEN ITEMS rather than guessing, records the result on the engagement file, and requires principal sign-off before workpapers are delivered. This goes well beyond the annotations without contradicting them.

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 front-loaded with the main action and scope, then adds only the necessary behavioral caveats about open items and sign-off. Every sentence contributes useful information without repetition.

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 ASC 606 computation tool with no output schema, the description covers inputs, scope, open-item handling, recording, and sign-off. It is largely complete, though it does not describe what the caller receives back from the computation beyond the fact that the result is recorded.

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 schema already documents engagement_id, transaction_price_usd, and all item fields including SSP method and separately_usable. The description reinforces the key inputs but does not add much parameter-level meaning beyond the schema; baseline 3 is 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?

The description states a specific verb and resource: running the ASC 606 five-step recognition for a general revenue contract. It identifies the exact steps handled (Step 2 obligations, Step 4 allocation, Step 5 timing), which distinguishes it from siblings such as compute_lease, compute_commission, and compute_close.

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 clearly scopes use to a 'general revenue contract' and says what inputs to provide: transaction price and promised items with SSPs. It does not explicitly name alternatives or when-not-to-use conditions, but the general-contract phrasing gives enough context for selection.

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 meaningful behavior beyond the readOnlyHint: it refuses rather than guesses when fair value is missing, posts nothing, and requires principal sign-off at close. That is exactly the kind of non-obvious trait an agent needs. Minor gap: it doesn't describe any precision/rounding or audit-trail behavior of the computation itself.

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?

Tightly packed prose with the core action front-loaded and the branch logic following in dependency order. The jargon density and em-dash clauses make it heavy, but no sentence 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?

With no output schema, the description carries the return-value burden and does so: it names the expense leg and revenue-reduction leg, the no-split case, and the refusal path. An agent can call this correctly and anticipate the response shape from the description alone.

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 goes further by explaining the accounting meaning of each input's branch (distinct good → split up to fair value; excess → revenue reduction; no distinct good → no split). This adds interpretive value the schema's one-line property docs don't supply.

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 ('Split a trade-spend payment to a customer') plus the governing standard (ASC 606-10-32-26 / 705-20-25-2). It is clearly distinguishable from accounting siblings like compute_revenue_contract, compute_commission, and compute_close.

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 says what inputs define the scenario (payment amount, distinct good/service flag, fair value) and how the branch condition changes the outcome. It does not, however, name an alternative tool or exclusion ('use compute_revenue_contract if...'), so routing among the many compute_* siblings is left to the accountant's judgment.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the critical non-obvious behavior: removing a member ENDS membership as-of a date rather than deleting it, past purchases stay attributed and only later ones stop rolling up. It also explains persistence ('what makes Aurgus remember') and the downstream effect ('the NEXT close matches them automatically'), which is exactly the kind of consequence an agent cannot infer from structured fields.

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 core purpose is front-loaded in the first clause and every sentence carries operational information. It is, however, a single dense paragraph heavy with em-dashes, parentheticals, and ALL-CAPS emphasis, which slows scanning for an agent parsing it against sibling definitions.

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, the description covers the input contract, the semantic effect of each path (add vs. end-as-of-date), the immutability guarantee, and the required next step. Nothing an agent needs in order to invoke it correctly and then recover the state 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 the baseline is 3; the description earns a step up by tying valid_from/valid_to to real-world events (a GPO join, an acquisition, a rename, a member leaving) and by distinguishing the additive 'members' path from the 'ended_members' path in prose. It largely mirrors rather than extends the per-field schema text, so it is not a full 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 and resource ('Record the human's answer to a customer-grouping question') and immediately scopes it to two concrete cases: a grouping compute_close proposed, or a roster change. It explicitly contrasts with the sibling that does the proposing ('grouping compute_close PROPOSED') and with Aurgus's own behavior ('Aurgus never changes a group on its own'), so an agent can tell this apart from compute_close 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 an explicit precondition ('Use ONLY after Aurgus surfaced the question and the user answered') and an explicit follow-up ('After confirming, run compute_close again to fold the change in'), which routes the agent through the correct sibling sequence. It also names the input-discipline rule ('pass the agreement_id and the name(s) exactly as they appear in the data') and when to set dates versus omit valid_from.

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 give readOnlyHint=false and destructiveHint=false; the description adds the material behavior: the key is scoped to DATA-INTAKE only, can never run a close/settle/move money, is a real credential requiring the explain-then-confirm flow, and the plaintext is returned exactly once and can be revoked in Account. This is consistent with the annotations and far exceeds them.

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?

Purpose and credential scope are front-loaded, and each sentence carries operational weight. It is a single dense block and repeats the label rule already present in the schema, which keeps it from being maximally tight.

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-optional-parameter write tool with no output schema, the description covers what is created, what the return contains (one-time plaintext key plus Zapier steps), what the credential can and cannot do, and how to reverse it. Nothing needed to call it correctly 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 the baseline is 3; the description still adds procedural meaning — confirm orchestrates a deliberate two-step explain-then-create flow with no re-asking, and label must be omitted unless volunteered. It largely mirrors the schema text rather than adding new syntax or constraints, so it lands just above 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?

States a specific verb and resource: connect an ERP/POS/order system (or Zapier) to Aurgus by creating an API key. It also names the mechanism (Aurgus Open-API /api/v1) and the data directions (transactions in, journal entries out), so an agent can tell this apart from ingest/export 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?

Explicitly says when to use it ('user asks to connect their system, integrate their ERP/POS, or set up Zapier'), states a prerequisite ('Requires a connected Aurgus account'), and prescribes the two-call confirm protocol including when to stop re-confirming.

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 declare destructiveHint=true, but the description goes well beyond that: it explains append-only reversal (originals and reversals both persist for audit), the clawback warning on already-settled postings, the ERP refusal path, and the auth requirement (connected Aurgus account). This is materially more than the annotation conveys.

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 core action, then the dry-run protocol, then prerequisites — a logical order. It is dense and heavy on capitalized emphasis, running longer than necessary, but nearly every clause 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?

No output schema exists, and the description compensates by describing exactly what the dry-run returns (posting count, dollar amount, settled warnings) and what applying does. Combined with the ERP refusal and account prerequisite, nothing essential is missing for correct invocation.

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 both params are documented there, so the baseline is 3. The description adds genuine value by framing confirm as a safety gate ('call WITHOUT confirm first to DRY-RUN') and by describing what the dry-run reports (posting count, $ reversed, settled/clawback warnings) — value beyond the schema text.

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+resource ('Retire a WRONG agreement that has already accrued — reverse its postings, then archive it') and explicitly contrasts itself with both plain voiding and superseding. An agent can distinguish this from close_agreement or edit_agreement 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?

Gives explicit when-to-use ('already accrued', 'WRONG'), when-not ('refuses if posted to ERP — supersede it instead'), and the two-step dry-run-then-confirm protocol. Alternatives and exclusion conditions are both named.

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 declare readOnlyHint=false and destructiveHint=false, but the description discloses far more: activation is blocked if the config isn't ASC-606-conformant, cadence/validity values must satisfy the type's contract, direction and type are posting-locked once a document hits the ERP. Most importantly it discloses the non-obvious side effect that a validity change raises a gated Recalculate card rather than posting money, and nothing is backdated without operator approval.

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 purpose and editable field list are front-loaded, followed by constraints and then sibling routing — a sound order. The constraint sentence is dense and clause-chained with four semicolon-separated rules, and the direction semantics are restated in both description and schema, shaving off the top score.

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 an eight-parameter, governed financial mutation with no output schema and only generic annotations, the description covers prerequisite access, contract validation, posting locks, approval gating of downstream recalculation, and alternative tools for adjacent operations. An agent has everything needed to call it correctly and predict its side effects.

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 eight parameters are already documented, including the enum for direction and the null-for-open-ended convention on valid_to. The description adds one genuinely new piece of meaning — patch semantics, "send only the fields to change" — but otherwise restates the schema's field meanings rather than extending them, so the baseline 3 holds.

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?

A precise verb plus resource ("Change an agreement's TERMS") immediately followed by the exact set of editable fields: name, counterparty, direction, validity window, cadence. It also explicitly names what this tool is NOT (rates, status), so the agent can distinguish it from edit_agreement_rates and close_agreement 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 gives an explicit routing rule — "To CHANGE RATES use edit_agreement_rates; to change STATUS use the audited status flow" — plus the calling convention "Send only the fields to change." The precondition (agreement_id required, connected Aurgus account) is stated, leaving nothing 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 only declare a non-read-only, non-destructive mutation; the description carries the real behavioral burden. It discloses the dry-run versus apply semantics, immediate effect on future transactions, the gated Recalculate card for past-period adjustments, that nothing is backdated through this tool, and the ERP-posted refusal condition.

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 dense but front-loaded: it first states what changes, then units, then the dry-run/apply protocol, then side effects and refusals. Every sentence adds operational value, with no repetition of the schema's property descriptions beyond essential unit conventions.

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 mutation tool with no output schema, the description covers the full calling workflow, side effects, approval gating, refusal conditions, account prerequisite, and scope limits. An agent has enough to decide whether to dry-run, apply, or use the supersede path instead.

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 baseline is 3, but the description adds useful semantics: rates are in percent (1.5 = 1.5%) and thresholds in dollars, and a no-edit dry run lists current regimes with their keys and rates. The parameter-level schema already documents confirm, regimes, and shared_tier_grid, so the description is reinforcing rather than the primary source.

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 (change rates on a rate-routed agreement) and explicitly distinguishes what is editable (rates) from what is not (routing dimension, regime keys, member values). It also distinguishes which kind of rate is targeted: flat, regime-specific tiers, or the shared tier ladder.

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 prescribes the two-step workflow: call without confirm to dry-run and list or echo, then call with confirm:true to apply. It also states a clear exclusion — 'Refuses if posted to the ERP (supersede instead)' — and notes the connected-account requirement, leaving little 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=true and destructiveHint=false, and the description still adds real behavioral substance: status is re-derived from events rather than trusted from storage, the close is blocked while open items remain, and the tool refuses to report if the hash chain fails re-verification. The refusal-on-tamper behavior is exactly the kind of non-obvious trait an agent must know before calling.

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 compact sentences, front-loaded with the core concept (derived, not stored) before the two modes and the failure case. Every sentence carries information — no restatement of the title or the 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?

There is no output schema, so the description carries the burden of describing returns, and it does: chain steps, what's next, open items, the no-id engagement list plus firm status, and the refusal path. Nothing an agent needs in order to call this correctly and interpret the result 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% and the schema already documents the omit-to-list behavior, so the baseline is 3. The description earns above that by tying the parameter to two distinct result shapes and to the no-id branch that also returns firm status, which the schema only states in compressed form.

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 — report where an engagement stands — and explicitly distinguishes itself from a stored-status read ("derived from the engagement file's real events, not a stored status"). An agent can tell this apart from compute_close, compute_* and report siblings because it is a read-side status derivation, and the two operating modes are spelled out.

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 explicit conditions for both modes: with an engagement id you get chain steps/next/open items, without one you get the client's engagement list plus firm status. That covers when to call it and how to pick the parameter, but it never names a sibling alternative (e.g. compute_close or report) to steer the agent away when a different tool is wanted.

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/non-destructive, so this tool is safe; the description adds behavior beyond that: it is deterministic and grounded, will not guess, asks which payment type applies when ambiguous, and returns treatment + ASC citation + rule applied. The 'will not argue a position' clause sets expectations no annotation could convey.

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 purpose and standards, then the exclusions and the handoff — every sentence earns its place. Slightly penalized for ALL-CAPS emphasis and a dense run-on framing that makes it heavier to parse than necessary.

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, but the description states what is returned (governed treatment, exact ASC citation, rule applied), how ambiguity is handled, and where to go for anything beyond a payment type. Nothing an agent needs to call it correctly 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 the baseline is 3. The description still adds meaning: it clarifies that `scenario` text is context only and does not drive classification, and that a missing payment type yields an options prompt rather than a failure. These are useful agent-facing behaviors even though most param detail lives in 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?

States a precise verb+resource (state the governed US-GAAP treatment for a payment type) and enumerates the exact standards/classification it covers. It is unmistakably distinct from the sibling compute_* tools, which run calculations rather than explain classification.

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 scopes in (payment-type treatment) and out (free-form Q&A, advisory debate, open questions), and routes the agent onward: 'For anything past the treatment of a payment type, run the engagement (compose/ingest the agreement, then compute).' That names both the exclusion and the alternative workflow.

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 and destructiveHint=false, so the safety profile is covered. The description usefully adds the auth prerequisite (connected Aurgus account), tenant scoping, and that all figures are computed off the canonical ledger. It does not disclose the delivery mechanism — whether the call returns a file, a download URL, or inline structured content — which is the key unknown for a tool named 'export'.

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 deliverable is front-loaded in the opening clause, which is good. But the single run-on sentence is padded with marketing phrasing ('the open accrual you can stand behind', 'where margin is leaking') and em-dash nesting, when a plain enumeration of the package contents would read faster.

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 parameters and no output schema, the description carries the burden of describing results, and it does partially substitute for an output schema by enumerating the three package components. It still omits output format, size/timing expectations, and any hint about how the result is retrieved, which leaves real gaps for an export-style tool.

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 empty schema (additionalProperties: false) leaves nothing for the description to explain. The description implicitly confirms there is no period/tenant argument to supply, since scope is fixed to 'your tenant'.

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 names the concrete deliverable (auditor-ready package containing open accrual, margin leakage vs. off-program spend, and sample lineage) and its data source (canonical ledger), which is far more specific than the bare name 'export'. However, it never distinguishes itself from the closely related sibling 'export_workpapers', nor from 'report'/'run_report', so an agent cannot tell which export to pick from the description alone.

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 only usage-adjacent content is the prerequisite 'Requires a connected Aurgus account'. There is no statement of when this tool should be chosen over export_workpapers, report, or run_report, and no exclusions or timing cues (e.g., period close, audit request).

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 establish readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: the tool refuses until the close is signed, reads from a hash-chained file, and combines concluded figures with unproven items on one page. It does not cover edge cases such as what refusal output looks like.

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 tightly written sentences front-load the deliverable, then state the refusal condition, then explain the significance of the combined output. Every sentence adds information without repetition.

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 one-parameter tool with no output schema, the description supplies the essential missing context: what the output contains, where it comes from, and the precondition for success. An agent has enough information to know when and why to call it.

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 there is only one required parameter, engagement_id, which the schema fully documents. The description adds no parameter-level detail beyond the schema baseline, so a 3 is 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?

The description states a specific verb-resource pair, 'Deliver the engagement workpapers', and specifies the contents: certified figures plus the open-items register on one page. It also names the source, the hash-chained engagement file, making it clearly distinguishable from siblings like open_items, export, and report.

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 prerequisite and usage condition: the tool refuses until a principal has signed the close, and frames the output as the auditor-ready deliverable. It does not explicitly compare this to alternatives such as export or report, so it stops short of a 5.

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 and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond annotations: the response content is the manual, and the tool is free with no account needed. It omits minor details like rate limits or response format, which keeps it from a 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?

The description is front-loaded with the usage condition and then explains the return value. The trigger-phrase list is slightly long but directly useful for matching user intent, and every sentence contributes to selection or expectation-setting.

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, the description compensates by explaining what the returned manual contains: what Aurgus is, how an engagement runs, trigger phrases, and how to start. For a no-parameter help tool, no important context 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?

The tool takes zero parameters, so the baseline is 4. The description correctly does not invent parameter semantics, and the empty input schema is self-explanatory.

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 action and resource: it returns the Aurgus manual and enumerates the manual's contents. It also distinguishes this tool from siblings like explain or release_notes by focusing on the broad how-to manual and trigger-word reference.

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 clear, concrete triggers for when to call the tool, including example user phrases like 'Aurgus help', 'what can you do', and 'show me the manual'. It does not name when not to use it or explicitly point to alternatives such as explain or release_notes, so it stops short of a perfect 5.

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 readOnly=false and destructive=false; the description goes further by disclosing the staging model — bad or blank amounts are held and reported rather than booked as $0, and nothing affects the tenant's numbers until a person certifies the mapping. That is exactly the kind of consequence an agent needs before calling. It stops short of covering re-ingest/duplicate behavior or partial-failure semantics.

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 dense but well-ordered sentences: the action and file taxonomy come first, then the operational guarantees. Every clause carries information (validation behavior, human certification, account requirement), with minimal 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 4-parameter mutating tool with a nested mapping object and no output schema, the description covers the account prerequisite, the validation/staging model, and human certification. What an agent gets back from a held-rows report, and whether re-ingesting the same file duplicates data, are the remaining gaps.

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 description largely restates what the schema already documents (the three kinds, mapping your columns to Aurgus fields). It adds the useful framing that the mapping is what a human later certifies, but no new syntax or validation rules beyond 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?

States a concrete verb ('hand ... to read into your tenant') and enumerates the three accepted file kinds with definitions for each. It is clearly an ingestion tool for rebate extracts, though it never distinguishes itself from the sibling ingest_agreement, so an agent must infer the boundary.

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 what to supply (raw CSV, kind, column mapping) and gives a hard prerequisite ('Requires a connected Aurgus account'), which is useful gating. But there is no when-not-to-use guidance and no routing versus ingest_agreement or receive_document, leaving the choice between ingestion siblings 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?

Beyond the annotations, it discloses key behavior: parsing is deterministic and LLM-free (with CPU CV/OCR for PDFs/scans), unclear spans are flagged rather than guessed, and no record is created until human review. This goes well past readOnlyHint=false and destructiveHint=false and tells the agent exactly what to expect.

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 front-loaded with the actionable instruction (paste text or drop a PDF) and then explains the parsing and review workflow. It is somewhat long and includes emphatic marketing phrases like 'ZERO LLM', but nearly every sentence contributes useful context.

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 ingest tool with no output schema, it explains the input paths, extraction scope, deterministic parsing, human review gate, and the fact that no transaction data is required yet. It could be slightly more complete about what the call returns or what happens between ingest and review, but the essential workflow is covered.

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 schema already documents all three parameters. The description still adds useful meaning by reinforcing the text-or-file_base64 alternative and clarifying that file_base64 may be a scanned document handled by OCR, which helps an agent choose the right input path.

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 and resource: ingesting a rebate agreement via pasted text or a PDF, then extracting customer, basis, rate/tier ladder and period with a deterministic parser. This clearly separates it from siblings like compose_agreement or receive_document, which do not describe extraction of rebate terms.

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 clearly places the tool in the workflow: use it to set up the agreement before any transaction data is asked for, and note that nothing is finalized until a person reviews and certifies in the browser. It does not explicitly name when to choose this over sibling tools such as receive_document or ingest, which keeps it from a 5.

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 and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned shape (name plus what each report measures) and the connection prerequisite, which the annotations do not convey.

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 sentences, both front-loaded with the essential noun and the alternative. No filler, no restatement of the title, and the prerequisite is tucked into a single clause rather than expanded into prose.

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 correctly compensates by naming the fields each entry carries, and it states the account prerequisite needed before the call can succeed. Minor gaps (ordering, whether the list is paginated or empty-state behavior) are not addressed but are low-risk for a zero-param tenant-scoped list.

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 no parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema is empty and closed (additionalProperties=false), consistent with the description's no-argument usage.

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 (list) and resource (saved analytics reports) plus scope (on this tenant) and even what each item contains (name + what each measures). It is clearly distinguishable from run_report, the sibling that executes a report rather than enumerating them.

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 routes the agent: use run_report with a name to re-run one, which is the natural next step after listing. It also states a prerequisite (a connected Aurgus account). It stops short of an explicit when-not, but for a zero-param enumeration tool the routing is effectively complete.

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 declare readOnlyHint=false and destructiveHint=false; the description adds substantive context beyond that: it starts a 'hash-chained, append-only record of everything that follows' and computes nothing. Append-only is meaningful behavioral disclosure about the durability of the record, though it doesn't mention permissions, whether an open engagement can be revoked, or what identifier the caller receives.

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 action, then the intake contents, then sequencing. Mostly tight, but 'This is how a firm begins: a named client and a scope, before any numbers' is somewhat atmospheric rather than operational.

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 non-destructive mutation with full annotation coverage and no output schema, the description covers what is created (an engagement file), what is not done (no computation), and what comes next (the agreement). It could still say what handle or state the caller gets back on success, but the core behavior is complete.

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 schema already documents all six parameters with examples. The description lists five of them (entity, period, programs, sources of truth, who_certifies) but omits 'direction' and adds no format or usage meaning beyond what the schema provides. Baseline 3 applies 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 ('Open a revenue-management engagement for a client') and immediately scopes it as intake capture only. Explicitly distinguishes itself from siblings by saying 'nothing is computed here' and 'the agreement comes next,' separating it from compute_* and compose_agreement/close_agreement tools.

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 clear sequencing guidance: 'This is how a firm begins: a named client and a scope, before any numbers' and 'The agreement comes next.' It doesn't name sibling tools explicitly or state exclusions (e.g., when not to open a new engagement vs. resume one), so it stops short of a 5.

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 declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden and does so with two useful traits: gaps are never filled on the client's behalf, and open items block signing the close. It does not disclose what resolving does to history or whether resolution is reversible, 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 compact sentences, front-loaded with the resource definition before the operations and the closing constraint. Slightly dense em-dash parenthetical, but every clause 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 five-parameter tool with no output schema, the description covers what the register is, what the actions do, and the consequence of leaving items open. It does not describe what a list returns (item fields, ordering, counts) or whether opening an item is idempotent, which leaves a small 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 is already documented inline, including which action each parameter applies to. The description reinforces this by tying resolution to an id, but adds no syntax, format, or validation 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?

The description names the resource (the engagement's open-items register), defines it concretely with three example item types (missing document, missing term, unmatched figure), and enumerates the three operations. An agent can tell this apart from content tools like receive_document or sign_close without opening the 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 states the three usable actions ('List them, open a new one, or resolve one by id') and adds a precondition that matters for sequencing: 'the close cannot be signed while any item remains open.' It stops short of naming an explicit alternative tool or stating when-not-to-use, so a 4 rather than a 5.

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 readOnlyHint=false and destructiveHint=false; the description adds the essential behavior: it writes accruals, is idempotent because positive-accrual rows are skipped, mirrors compute_close's engine, and requires a connected Aurgus account. That is exactly the beyond-annotation context a caller needs for a mutation tool.

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 verb and engine scope are front-loaded, and each clause carries weight (eligibility trigger, idempotency, param behavior, return value, auth). It is dense and slightly overpacked with parentheticals, but no sentence 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?

With one optional param and no output schema, the description covers everything the agent needs: trigger condition, mutation semantics, idempotency, parameter effect, return value (events created plus accrual total), and the account prerequisite.

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 single parameter is fully documented in the schema itself ("Recompute just this agreement. Omit to recompute all active agreements."). The description restates the same distinction without adding format, constraints, or examples, 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?

"Re-run the deterministic engine over the POS data" is a specific verb + resource, and the description immediately distinguishes the tool from compute_close by noting it posts the same provisional accruals. An agent can tell what it does and how it relates to the closest sibling.

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 explains when this is the right call — rows that just became eligible after a data fix or rule change — and states that already-accrued rows are skipped so a repeat run is unnecessary. It stops short of naming an explicit alternative or exclusion case (e.g. when to prefer close_agreement), keeping it at 4.

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 readOnlyHint=false and destructiveHint=false; the description goes well beyond that by disclosing server-side fetching, staging inside the client's tenant for certification, resolution of the PBC open item, and the deliberately narrow return surface (column names plus where to certify the mapping). It also makes an important safety guarantee explicit: no rows of client data pass through the model.

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 right idea, but the by-reference point is restated three times ('BY REFERENCE', 'never the file's contents', 'doesn't touch the model', 'no LLM on the money path') and the closing tagline is rhetorical rather than informative. Roughly a third of the text could be cut without losing guidance.

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, the description usefully says what comes back (column names and the certification location), which is exactly what an agent needs to continue the workflow. It omits failure modes (expired link, unreachable URL, wrong tenant) and whether the call is idempotent for a given open item.

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, but the description adds real meaning: it explains that signed_url and upload_handle are mutually alternative delivery mechanisms and that contents are never pasted in, which reinforces the 'by reference' contract in the schema. It still does not clarify required-vs-optional selection between the two transport params.

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 ('receive a client document into an engagement') and immediately pins down the mechanism ('BY REFERENCE — a signed https link or upload handle, never the file's contents'). That mechanism is what separates it from siblings like ingest or request_documents, so an agent can route correctly without opening the 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?

Usage is implied: it is the path for getting client data in, and it 'resolves the matching PBC open item', which hints at the post-request step. However, it never names an alternative (request_documents, ingest) or states an explicit when-not-to-use condition, so the agent must infer the ordering from sibling names.

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 past the readOnlyHint/destructiveHint annotations by disclosing cost ('Free'), auth requirements ('no account needed'), and data scope ('reads nothing from any tenant'). It also previews the returned content, so an agent knows what it will get back without an output schema.

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-loads the purpose statement before the trigger list and the content summary, so the most important information comes first. The parenthetical feature inventory is dense but each item earns its place by telling the agent what the response contains.

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 inputs, no output schema, and minimal annotations, the description carries the full burden and does so: it explains the return contents, the auth/cost profile, and the data-access boundary. Nothing an agent needs in order to call it correctly 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly adds nothing spurious about inputs.

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 concrete verb and resource: it returns the current release summary (naming the specific feature areas covered) plus a test checklist. The purpose is unmistakable, though it never names a sibling like help or explain, so an agent must infer the boundary from the trigger phrases alone.

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 explicit invocation triggers ('what changed', 'release notes', 'what's new', 'changelog') and an additional scenario (reviewing/pressure-testing the product). It stops short of stating when NOT to use it or pointing to an alternative for adjacent questions that could land on help or explain.

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 and destructiveHint=false, so the description earns credit for adding context beyond them: it explicitly says it 'computes nothing new, it reports the canonical ledger' and that it 'Requires a connected Aurgus account' — a real auth prerequisite an agent needs. It stops short of disclosing whether the list is bounded or paginated.

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 lead sentence front-loads the resource and the returned fields, and the mode/argument instructions follow logically. Slightly padded by the 'book-at-a-glance a controller watches' framing, but no sentence is redundant with the 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?

With no output schema, the description usefully enumerates the returned fields (accrual breakdown, basis, status, last calculated), which is exactly what an agent needs to judge relevance. Remaining gaps are minor: no list-size/pagination behavior for 'every active agreement' and no precedence rule when both parameters are passed.

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 both optional parameters are already documented, making 3 the baseline. The description restates the agreement_id/status modes and enumerates four status values, but omits the 'all' enum value and never says what happens if both parameters are supplied together.

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+resource: returns every active agreement with earned/settled/open accrual, basis, status and last-calculated timestamp, plus the single-agreement mode. That is far more specific than the name 'report' alone. However, it never distinguishes itself from siblings like run_report, list_reports, or export, which an agent will see in the same namespace.

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 the invocation modes (pass agreement_id for one, status to filter the list) and frames the use case as 'the book-at-a-glance a controller watches.' That implies when to call it, but there is no explicit when-not, and no routing against run_report, list_reports, or export, which are the obvious confusable siblings.

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 write-ish but non-destructive; the description adds real behavioral weight: the tool creates open items and hard-gates the close ('the close can't be signed until every one is received, mapped and certified'). It omits idempotency (what happens on a re-run when a list already exists) and the error mode when the agreement has no matching rule.

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 action and scope; the mid-sentence examples (sell-side rebate → POS extract) earn their space by showing the derivation logic. The stacked parentheticals make it denser than it needs to be, but there is 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?

With no output schema and only minimal annotations, the description carries the burden well: it covers the source of truth (the agreement), the downstream consequence (open items gating sign-off), and the precondition. Return shape and duplicate-handling behavior are the remaining gaps, which matter less for a one-parameter drafting call.

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% for the single engagement_id, so the schema already does the documentation work. The description adds only the implicit precondition that the referenced engagement must carry an active agreement, which is useful but thin — 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 + resource: 'Draft the PBC (prepared-by-client) document list for an engagement, FROM its agreement.' The parenthetical expansion and the derivation-from-agreement clause make the purpose unambiguous. It doesn't explicitly name a sibling it is not (e.g., receive_document, open_items), so it falls just 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?

Gives a clear precondition ('Needs an active agreement first') and a usage signal that it is derived, not generic ('never a generic ask'). It does not state when to use an alternative such as receive_document for already-collected files, nor what to do when a list already exists.

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 declare readOnlyHint=false / destructiveHint=false but say nothing about what actually happens. The description fills that gap: it discloses that the tool hands back a link, that nothing is posted to the GL (no ledger mutation despite the write-ish hint), and that supplying an email sets up access/follow-up — a real side effect the agent should know about before passing PII.

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 action is front-loaded, but the opening sentence is loaded with marketing adjectives ('audit-defensible accruals, full lineage, and an auditor-ready export') that don't help an agent decide or invoke. The usage rule and the email warning are buried as trailing clauses of one long sentence rather than separated.

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 only two optional parameters, no output schema, and thin annotations, the description covers what an agent needs: what it returns (a link), what it doesn't do (no GL posting), and the consent rule around email. The unmentioned `scenario` param is the only real hole.

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 baseline is 3. The description reinforces the `email` contract ('only what the user volunteers', never solicit financial data in chat), which is genuinely useful consent guidance, but the `scenario` parameter is never mentioned anywhere in the description.

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 concrete action — 'get the link to run a real close on your OWN numbers' — plus the input it expects (a rebate/SPA/deduction extract) and the outputs (accruals, lineage, export). It is clear enough to act on, but it never distinguishes itself from nearby siblings such as `begin`, `open_engagement`, `ingest`, or `sign_close`, so an agent must infer which entry point applies.

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 this when the user is ready to move from a sample to their own data' gives an explicit trigger condition, which is more than most siblings offer. It also states an exclusion-style rule ('never ask for financial data inside the chat'), but there is no named alternative for the sample-vs-real boundary or for users who aren't ready.

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 and destructiveHint=false, and the description reinforces this with 'governed and read-only exactly like `analyze`'. It adds value beyond the annotations by stating the return content (grouped rows + total) and the connected-account requirement, though it says nothing about cost, rate limits, or failure modes when the saved report is missing.

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 dense sentence that front-loads the action and then the return and the account requirement; nothing is redundant. It is slightly overloaded — the 'governed' phrasing is vague and adds little.

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 one-parameter, non-destructive read with full annotations and no output schema, the description covers action, data freshness, return content, and the auth prerequisite. Only edge behavior (unknown name, empty results, report-parameter overrides) is left implicit.

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 a single parameter at 100% schema coverage, the schema already defines `name` and points to `list_reports`. The description contributes only the qualifier 'by name on current data', which hints that the saved definition is re-executed rather than returning a cached snapshot, but gives no naming/format detail beyond 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?

The description gives a specific verb and resource ('Re-run a SAVED analytics report by name') plus the return shape ('grouped rows + total'), which separates it cleanly from save_report, list_reports, and analyze. An agent can select it without opening the 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 establishes the precondition ('Requires a connected Aurgus account') and equates behavior with the sibling `analyze`, and the schema points to `list_reports` for name discovery. What's missing is an explicit exclusion — e.g. when to use `analyze` for ad-hoc questions instead of a saved report.

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 declare it is a non-read, non-destructive write. The description adds the non-obvious upsert behavior ('re-saving the same name updates it'), that a governed spec is persisted, and the auth prerequisite — real value beyond structured fields. It stops short of saying what happens to a spec when an agreement/dimension is later removed, or error behavior on name collisions with different specs.

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 clauses, front-loaded with the action, then the payload, then the upsert caveat, then the downstream tool and prerequisite. No sentence is filler; the parenthetical enum hint is compact rather than redundant.

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 tells the agent what is stored, how it is keyed, how it is mutated, and how it is consumed later — enough to call it correctly and reason about consequences. Remaining unknowns (return payload shape) are low-stakes for a save operation.

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 a notch by framing all fields as 'the same measure / group_by (/ dimension_key / agreement_id) you'd pass to analyze', giving the agent a way to derive correct values from a familiar call rather than reading the enum lists cold.

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 + purpose ('Save an analytics report for reuse') and immediately distinguishes itself from siblings by naming `analyze` (source of the spec) and `run_report` (later re-execution). An agent can place it in the lifecycle without opening another 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 states what to pass, that re-saving the same name updates rather than duplicates, that `run_report` is the follow-up, and the precondition of a connected Aurgus account. Effectively covers when-to-use and which sibling to reach for next.

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 declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by stating a connected Aurgus account is required, that cadences can be set or changed later, and that supplying settlement_approver_email causes Aurgus to hold every settlement until a one-time email approval lands. Those are real behavioral consequences an agent cannot infer from structured fields.

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 purpose, then a numbered enumeration of the two decisions the user must be asked. Slightly long because it re-lists enum values already in the schema, but each sentence (account requirement, one-or-both, change-later) carries 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 non-destructive 4-parameter mutation with no output schema, the description covers prerequisites, partial updates, and the approval side effect. It does not say what the tool returns or what happens with invalid combinations (e.g., 'threshold' without a threshold value), leaving a small 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 coverage is 100%, so baseline is 3; the description earns a bump by glossing the cadence values with meaning the schema mostly omits ('realtime as sales land', 'threshold when a dollar threshold is hit') and by stating that only one cadence need be passed. It adds nothing about settlement_approver_email beyond the schema, so not 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?

Opens with a specific verb+resource pair: 'Set how often an agreement ACCRUES and SETTLES.' This clearly separates it from execution-oriented siblings like settle, close_agreement, and compute_close, which act on money movement rather than configuring cadence.

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 frames the usage context: 'Ask the user these when setting an agreement up (or to change them later)' and clarifies 'you can set one or both.' It does not name a sibling alternative (e.g., edit_agreement_rates) for callers wondering where related edits belong, so it stops short of full when/when-not routing.

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 readOnlyHint=false, destructiveHint=false; the description goes well beyond by disclosing that the call zeroes an open balance, that dry-run returns the payout preview plus any blocking gate (named approver, incomplete agreement, anomaly hold), and that the same gates back the workspace Settle button. Account-connection requirements are also surfaced, which annotations never convey.

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 critical information — verb, money direction, balance effect — is front-loaded, and the sibling disambiguation follows logically. Slight cost: the confirm dry-run/post protocol is restated from the schema's own parameter description, so a sentence of redundancy keeps it from 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?

For a 2-parameter mutation with no output schema, an agent gets everything it needs: prerequisites, the two-step invocation contract, what the dry-run surfaces, what gates can block, and what state change results. Nothing material is left to inference.

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 schema carries the mechanical definitions and baseline is 3. The description adds real meaning on top — it explains what the dry-run actually reports (open accrual to be paid and which gate blocks it) rather than just restating that confirm is a boolean preview/post switch.

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 ('Settle an agreement — post the PAYOUT') and spells out the concrete effect: per-bucket Settlement events totalling earned minus already settled, driving the open balance to $0. It also explicitly distinguishes itself from compute_close (accrues) and true_up (reconciles), so an agent can pick it out of a crowded sibling list without reading schemas.

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 the full selection logic: this is the money-OUT step versus compute_close and true_up by name, and within the tool it prescribes a two-call protocol — first without confirm to dry-run, then with confirm:true to post. Prerequisites ('Needs the agreement_id', 'Requires a connected Aurgus account') are stated outright.

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 it is a non-readonly, non-destructive write; the description adds the substance: the open-items register gates the call, a computed close is required, the actor must be the principal rather than the client, and the signature is what releases the workpapers. That is genuine side-effect and authorization context beyond the structured 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?

Three tight sentences: what it does, the refusal conditions, then the actor constraint and consequence. Front-loaded and free of repetition.

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 one-parameter mutation with no output schema, the definition covers preconditions, authorization, and the downstream effect on workpapers. It does not say whether signing is idempotent, whether it can be retracted, or what the response contains, which leaves a modest 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 coverage is 100% for the single engagement_id parameter, so the baseline is 3. The description adds a meaningful clarification that the signer is not a parameter because the identity is the authenticated principal, which prevents an agent from searching for a signer field.

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 (signs) against a specific resource (the governed close) with scope (per engagement, by name, on the engagement file) and actor (the principal). It distinguishes itself from the neighboring compute/agreement tools by tying the signature to a previously computed close.

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?

Preconditions are spelled out concretely: it refuses while any open item remains, and a close must already have been computed, which implicitly routes the agent to open_items and compute_close first. A constraint on who may sign (not on the client's behalf) is also given. It stops short of naming the prerequisite tools explicitly.

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 and destructiveHint=false, so safety is covered. The description contributes the lineage-chain structure and the account prerequisite, adding useful context beyond the annotations, though it doesn't describe output format or pagination.

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 sentences, zero waste, with the operation and its chain steps front-loaded before the auditor rationale and prerequisite. Nothing extraneous.

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 read-only, two-parameter tool with no output schema, the description conveys enough: what the lineage chain contains, the account requirement, and the auditing purpose. Return shape is not specified but no output schema exists, so a minor 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 both parameters (source_transaction_id and optional agreement_id) are fully documented in the schema. The description only adds 'for a given transaction,' which is baseline-level value 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 concrete operation — walking an accrued figure back through the lineage chain (source row → eligibility → bucket → rate → rule → event chain) for a given transaction. This is a distinct verb+resource that clearly separates it from compute_*, analyze, and explain 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?

Provides a clear use case ('how you show an auditor exactly why a number is what it is') and a prerequisite ('Requires a connected Aurgus account'). It doesn't explicitly exclude or contrast with siblings like explain or analyze, so a 4 rather than 5.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the mutation's shape: exactly ONE Adjustment, signed as settled − earned, always current-period never backdated, append-only and idempotent. It also states the dry-run default and an auth prerequisite (connected Aurgus account), which annotations do not cover. Nothing here contradicts the non-destructive hint, since the write is an append-only adjustment.

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 core action and effect, then the sign convention, then the dry-run workflow. It is dense and occasionally repetitive ("Always current-period, never backdated" restates the period point), but nearly every sentence carries operational 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?

With no output schema, the description still characterizes what the agent will see (the exact Adjustment and before/after on a dry-run) and what the result means (open balance nets to $0). Given only two parameters and a non-destructive write annotation, this leaves no meaningful gap for correct invocation.

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, but the description adds value beyond the schema: it explains that a bare call dry-runs and shows the exact Adjustment plus before/after state, which the schema's terse confirm description does not convey. It also reinforces that agreement_id is mandatory via "Needs the agreement_id."

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 and resource ("True-up an agreement") and immediately pins down the mechanic: it matches the accrual account to what was actually settled by posting one signed Adjustment. It distinguishes itself from neighbors like settle and close_agreement by explicitly noting that close-out runs this true-up as its first step.

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?

Timing is explicit ("AFTER a settlement"), the alternative path is spelled out (call without confirm to dry-run, then with confirm:true to apply), and the relationship to close_agreement is named. An agent knows exactly when this tool applies and when to reach for the sibling instead.

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