schedule-iii

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

The description reveals critical behaviors beyond annotations: the confirmation is pinned to the exact reviewed set and any later save to that section withdraws it; it notifies the named member; it requires generating a fresh version after capture changes because finalisation checks the frozen capture state. These traits are not indicated by the readOnly/destructive hints, so the description fully carries the burden.

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 every sentence contributes important context, including warnings and behavioral nuances. It is front-loaded with purpose and then logically flows into usage, exceptions, and versioning. It is longer than average but earns its length. Minor redundancy exists between 'Saving figures or text does NOT complete these two sections' and 'Every other section is answered by saving its rows,' but this reinforcement is acceptable.

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 and low schema coverage, the description covers the essential context: what to do, what not to do, the specific sections, the side effects, and the unusual withdrawal behavior. The only gap is an explicit mapping of capture_kind values to the two sections, but reason_code covers that differentiation, so the description is nearly complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (29%), but the description clarifies the meaning of the two critical enums: reason_code (comparative vs disclosures) and capture_kind implicitly by tying the action to the two sections. It also explains the on_behalf_of side effect (notification). However, it does not explicitly explain client_id, template_id, period_id, or note, leaving some burden unmet for a 7-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Record your user’s confirmation that they have REVIEWED a whole section and it is complete.' It clarifies the two specific sections (previous-year comparative and disclosure set) and distinguishes itself from siblings by stating that every other section is answered by saving rows or declare_capture_na. This uniquely identifies the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is provided: before calling, show the user the entire section and obtain explicit go-ahead; never confirm an unreviewed section; saving figures does not complete these sections; if the confirmation doesn't stick, re-review and confirm again, never retry. It also clearly states that only two sections take a review confirmation and every other section uses save_* or declare_capture_na, naming the alternative directly.

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 annotations (destructiveHint=true, readOnlyHint=false), the description discloses key behaviors: omitted accounts remain unchanged, no auto-confirm, and the tool never returns rupee amounts. It also states the post-write report fields (confirmed, unmapped_total, unmapped_with_balance), adding clarity about side effects and output.

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 five sentences, each serving a purpose: purpose, pre-call requirement, behavioral constraints, output summary, and a safety note. It is front-loaded with the primary action and remains concise, though slightly longer than strictly 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?

With no output schema, the description compensates by explaining what the agent should report after the write. Combined with the detailed input schema and annotations, it provides enough context for an agent to use the tool correctly, including preconditions and post-conditions.

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. The description does not add new parameter-level meaning beyond the schema; it references 'enumerated items' and approval but doesn't elaborate on removal_token or effective_from specifics, which are already described well 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 opens with 'Persist only the explicit account-to-centre decisions the user approved,' which specifies a clear verb (persist) and resource (account-to-centre decisions). This distinguishes it from sibling tools like confirm_column_mapping or confirm_groupings by focusing on centre mappings specifically.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit when-to-use guidance: 'Before calling, show the proposal grouped by confidence tier... and get a clear approval.' It also indicates a when-not by stating there is no apply-all or auto-confirm flag. However, it does not explicitly name alternative tools for generating proposals, only implies them.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description adds valuable behavioral detail: it never auto-applies mapping suggestions, returns a full validation result (row counts, warnings, blocking issues), and advises reviewing warnings before ingestion. This goes beyond the annotations and clarifies side effects 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 three sentences, front-loaded with the core purpose, and every sentence adds unique value (purpose, return value, usage caveat). There is no redundancy or fluff, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a complex options object and no output schema. The description covers the primary workflow and return summary, but it leaves the many options entirely unexplained, and does not mention what save_as does. Given the tool's complexity, the description is not fully complete for an agent to invoke it optimally without further guidance.

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 only 25%: only upload_id is described. The description clarifies the mapping parameter by stating it must be exactly what the user approved, but it provides no guidance for the nested options object or save_as. With low schema coverage, the description only partially compensates for the missing parameter semantics.

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 opens with a specific verb-resource pairing: "Confirm the column→field mapping for a staged upload and run validation." This clearly distinguishes it from sibling confirm tools (e.g., confirm_centre_mappings, confirm_groupings) by focusing on column mapping for uploads. The return value is also described, adding further clarity.

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 description gives clear usage context: "Mapping suggestions are never auto-applied — pass exactly the mapping your user approved" and "Review any warnings with your user before ingesting." This implies a workflow (after upload, before ingestion) and warns against auto-applying suggestions, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

Despite annotations already marking destructiveHint=true, the description adds substantial behavioral detail: omitted accounts stay unchanged, only explicit leaf_code:null clears, clearing returns an approval request before any change, and the exact resend/approval flow. It also discloses idempotent behavior for already-unclassified accounts and deliberately no apply-all option, far exceeding what annotations alone 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?

Six sentences deliver multiple high-value caveats without redundancy. The opening sentence states the primary purpose, followed by concise, ordered details on omission, clearing, approval flow, idempotency, and the no-apply-all constraint. Every sentence contributes operational guidance, and the length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complex two-step clearing behavior and no output schema, the description covers most critical workflow aspects well. It explains what changes, what does not, idempotency, and the approval request flow. It falls short only in not naming the exact removal parameters or describing the success response, leaving slight ambiguity around the approval details.

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 only 17%, so the description carries heavy responsibility. It clarifies critical parameter semantics: decisions must be explicit, leaf_code:null means clear, and grouping_version must be current from list_grouping_suggestions. However, it does not explicitly explain removal_count and removal_token, only hints at 'approval details', and optional fields like suggested_reason, is_cash_equivalent, and suggested_confidence are not addressed.

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 opens with 'Persist USER-approved account→line groupings', a specific verb-plus-resource statement that clearly identifies the tool's function. It distinguishes itself from sibling confirm_* tools by naming the exact resource type (account groupings) and emphasizes it is a user-approved confirmation action.

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 description gives clear context for when to use the tool: after user approval, with explicit rows, and notes 'no apply all suggestions' alternative. It also names a prerequisite source (list_grouping_suggestions) for grouping_version when clearing. However, it does not explicitly compare against sibling confirm_* tools, though the resource-specific wording makes the distinction 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial behavioral detail: 'Sending leaf_code:null permanently removes that account saved reporting line,' 'Omitted accounts stay unchanged,' and the warning to never claim completion without checking the response fields. This goes well beyond the annotations and discloses important side effects.

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 five sentences and every sentence carries essential information—purpose, preconditions, null semantics, no apply-all, and response interpretation. It is front-loaded with the core action, but the density of warnings makes it longer than absolutely minimal, which is appropriate for a destructive 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?

Given the tool's complexity—four parameters, a nested decisions array, destructive behavior, and no output schema—the description is remarkably complete. It covers prerequisites, user approval steps, edge cases, response fields to check, and the caution not to assume completion. This fully compensates for the missing output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, and the description enriches the most critical parameter: leaf_code:null is explicitly linked to permanent removal, and the decisions array is clarified by noting omitted accounts stay unchanged and there is no auto-confirm flag. It does not explain removal_token, but the schema already describes its purpose adequately.

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 opens with 'Persist only the explicit reporting-line decisions the user approved'—a specific verb (persist) and resource (reporting-line decisions). It clearly distinguishes from sibling confirm tools like confirm_centre_mappings and confirm_column_mapping by narrowing scope to reporting-line mappings.

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 description provides explicit when-to-use guidance: 'Before calling, show the proposal grouped by confidence tier... and get clear approval.' It also gives when-not-to-use cautions, such as sending leaf_code:null only when the user explicitly asked to clear the row, and notes there is no apply-all flag. However, it does not explicitly name alternative tools, so it falls short of a perfect score.

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 (write, non-destructive), the description adds crucial behavioral details: it doesn't touch already-answered sections, review confirmations are never inherited, and finalisation uses the frozen version state rather than current state. No contradictions.

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 every sentence carries meaningful safety/behavioral information; slightly long but front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool without an output schema, it covers purpose, exclusions, user approval requirement, and versioning behavior. It does not mention return values or errors, but those are not essential given the context.

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 describes only client_id and on_behalf_of; the description does not clarify period_id or template_id semantics, and does not explicitly map "previous period" to any parameter. It leaves half the parameters undocumented.

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 explicitly states the tool copies "nothing this period" and "does not apply" answers from the previous period into the current period, only for sections without answers. This specific verb+resource+scope clearly distinguishes it from sibling save/confirm/revoke declaration 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?

It gives an explicit required precondition: list what would be copied and obtain user approval. It also states an exclusion (never copies review confirmations) and a workflow note about generating a fresh version after capture changes, so usage context is strong.

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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description supplements this with a 'Manager-role key' requirement and the need to show the name to the user first, adding meaningful context about auth and confirmation behavior. It does not contradict annotations.

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 consists of three concise sentences, front-loaded with the core purpose, then the auth requirement, and finally the usage/confirmation guideline. Every sentence adds value with no redundancy or 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?

The description covers purpose, auth requirements, and a usage constraint, which is good given the simple tool signature. However, it omits the optional business_model_code parameter entirely and provides no indication of return values or post-create behavior, leaving some important context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only vaguely references 'the name' but does not explain the required 'name' parameter or the optional 'business_model_code' parameter, their constraints, or their purpose. This leaves an agent without crucial parameter-level understanding.

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 uses a specific verb ('Create') and a clear resource ('new entity (company)'), which distinguishes it from sibling tools like create_cost_centre and create_profit_centre that create different resource types. It clearly identifies what the tool does without ambiguity.

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 description gives an explicit condition for use: 'Use only when the user explicitly asks to set up a new entity' and adds a required confirmation step ('show them the name you will create first'). However, it does not mention alternative tools or when not to use it beyond the 'only when' clause, so it misses the top tier.

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 indicate this is a write operation (readOnlyHint=false). The description adds valuable behavioral context: the user must be shown the exact parameters before creation, there is no bulk/apply-all behavior, and a post-create verification step is required. This goes beyond the basic write semantics and helps the agent understand the intended interaction flow.

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 concise sentences, each earning its place: the first states the action and required confirmation, the second clarifies scope (one at a time, no shortcut), and the third gives the mandatory follow-up action. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create tool with 8 parameters and no output schema, the description covers the essential workflow: pre-conditions (user confirmation), constraints (one at a time), and post-conditions (call list_cost_centres). It does not explain return values, but the follow-up instruction effectively compensates by telling the agent how to verify the result and continue the workflow.

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 input schema already covers all 8 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaning by identifying which parameters are user-facing and must be confirmed (name, kind, parent, effective date, reason), and by emphasizing that only one centre is created at a time. This is a helpful layer above 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 clearly states the action ('Create one cost centre for an entity') and specifies the exact fields to be confirmed with the user (name, kind, parent, effective date, reason). It also distinguishes this tool from a bulk or apply-all operation by explicitly saying there is no shortcut, setting it apart from sibling tools like create_profit_centre.

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 description gives clear usage context: show the user the exact details before creating, create one at a time, and follow up by calling list_cost_centres again to explain which mapping suggestions can use the new centre. It does not explicitly mention alternatives or when not to use this tool, but the workflow is well-defined.

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 indicate this is a mutating, non-destructive operation. The description adds valuable behavioral context: it confirms a user-confirmation step before creation and states that centres are re-listed afterwards, which goes beyond the basic annotation flags.

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 three sentences, front-loaded with the primary action, and every sentence adds value: scope, a limitation, and a post-creation behavior. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 params, no output schema) and available annotations, the description covers purpose, workflow (confirmation), and post-creation listing. It does not detail return values or error scenarios, but the mention of re-listing centres supplies practical context.

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 parameters are fully documented in the schema. The description mentions "exact name, optional parent, and description" which maps to name, parent_profit_centre_id, and description but does not add additional meaning 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 clearly states "Create one profit centre for an entity" with a specific verb and resource, distinguishing it from siblings like create_cost_centre. It also notes there is no apply-all shortcut, reinforcing its single-resource scope.

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 description gives a clear usage context: create one profit centre at a time, after showing the user the exact name/parent/description. It also states an explicit limitation (no apply-all shortcut), though it does not name alternative tools or explicit when-not-to-use.

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 minimal annotations (readOnlyHint=false, destructiveHint=false). Discloses single-use, login-free, 15-minute expiry, staging for one entity, and the key fact that nothing is ingested until column mapping is confirmed. Also mentions the file never passes through the assistant, preventing truncation/corruption.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose/benefit, when to use, and behavioral lifecycle. No redundancy, front-loaded with the action, and highly scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the schema is well-documented and the description covers usage, benefits, expiration, and security, it is nearly complete. The only minor gap is lack of explicit mention of the return value (the link URL), but this is strongly implied by 'mint' and not required for selection/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?

Input schema has 100% description coverage; the tool description adds no new parameter-level details beyond what's already in the schema. It reinforces the trial-balance context but doesn't explain any parameter more than the schema does. Baseline of 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 opens with 'Mint a single-use, login-free upload link' – a specific verb ('mint') and clear resource ('upload link'), distinguishing it from siblings like upload_trial_balance and get_upload_link_status. The benefit ('file never passes through you') reinforces the distinct purpose.

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 when to use: 'Use this whenever a human has the file (a trial balance export, etc.)'. It also provides the alternative context via schema param description: 'any other format is refused (use the Datavrn web app)'. This gives clear guidance without naming siblings directly.

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 substantial behavioral context beyond annotations: the declaration is a professional assertion requiring user authorization ('ask which one is true, and never guess'), answers are never edited in place and must be revoked first, and a fresh version must be generated after the last change because finalisation checks the frozen capture state. No contradiction with readOnlyHint=false or destructiveHint=false.

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 long but information-dense; every sentence delivers critical domain rules (allowed reason codes, restrictions, alternatives, versioning). It opens with a clear purpose statement and then elaborates. It could be slightly tightened, but the structure is logical and front-loaded.

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?

Despite no output schema, the description fully covers the tool's complex business rules: three distinct assertions, per-section allowed reason codes, specific capture_kind restrictions, the alternative review tool, the revoke workflow, and the version-frozen finalisation requirement. This is complete for an agent to invoke correctly without needing further clarification.

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 low (29%), but the description compensates well for the two enum parameters: it explains the meaning of the three reason_code values and gives concrete restrictions per capture_kind value. However, it does not explain the 'note' parameter semantics or the 'period_id'/'template_id' beyond what schema names show, so a small gap remains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool records a capture section as having nothing to report, not applicable, or first year, with a specific verb ('record') and resource ('capture section'). It distinguishes from siblings by explicitly pointing to confirm_capture_review for review completion, and from save_* tools by focusing on absence-of-data declarations.

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 explicit when-to-use guidance: tells the agent to call get_schedule3_workspace and read allowed_reason_codes, outlines per-section restrictions (settings takes no answer, share/partner capital only 'nothing this period', first-year only for previous-year figures), and names confirm_capture_review as the alternative for review completion. Also explains the revoke-then-recreate workflow for changing an answer.

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

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

The description discloses many behavioral traits beyond the annotations: 'THERE IS NO UNDO', refusal if the statement changed, the reused-as-true behavior, the status field semantics, and the asynchronous polling requirement. It also emphasizes the professional-judgment caveat about acknowledgments. This is rich context that the annotations (readOnlyHint: false, destructiveHint: false) do not provide.

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 long but each sentence earns its place, given the irreversible, high-stakes nature of the operation. It is front-loaded with the purpose and immediately follows with critical caveats (no undo, not approval), then step-by-step workflow, then failure-mode handling. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the irreversible action, preconditions, failure modes, and follow-up actions (poll get_job). It does not give a full response schema, but it highlights the key response fields (reused, status, job_id) and explains each relevant scenario. This is adequate for an agent to act correctly, though a fully specified response structure would make it 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema has only 40% description coverage, the description adds meaning to key parameters: confirm_token and acknowledgments are explained in context ('send the confirm_token it gave you together with the acknowledgements', 'never write the acceptance reason yourself'). It also implies the on_behalf_of field via 'recorded as authorised by the member you name'. However, snapshot_id is not explicitly tied to a parameter, so there is a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Seal a statement version as Datavrn’s permanent client copy, recorded as authorised by the member you name.' It uses a specific verb ('seal') and resource ('statement version'), and goes further to distinguish itself from approval/adoption/signature, which also helps differentiate it from sibling tools like get_finalise_readiness.

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 description gives explicit usage instructions: 'Call get_finalise_readiness first', 'get their explicit go-ahead', 'Do not call finalise_statement again' in the reused case, and 'Poll get_job with the job_id'. It also names the alternative (get_finalise_readiness) and explains when not to call the tool.

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

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

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses the background job nature, refusal conditions, acknowledgment dependencies, and expected user communication. It fully exposes the behavioral contract of the 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 description is long but dense, with every sentence serving a purpose. It is front-loaded with the primary action and return value, then methodically covers refusal and multi-month handling. No wasted words given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 8-parameter schema and no output schema, the description covers the async flow, user-consent requirements, and polling guidance. It does not enumerate possible errors or describe the resulting workbook contents, but it is sufficient for correct invocation and follow-up.

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 only 13%, but the description compensates by explaining the semantics of acknowledge_count/acknowledge_reason and acknowledge_multi_month_pnl/acknowledge_month_count, including their interdependencies. However, template_id and period_id remain largely unexplained beyond the schema, leaving a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action: 'Queue the Schedule III workbook build' and notes the async job_id return, distinguishing it from sibling get_*/save_* tools. It leaves no ambiguity about the tool's core function.

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 explicit instructions on handling refusal conditions (present ungrouped accounts, obtain user go-ahead, record reason and count) and directs the agent to poll get_job after queueing. This is precise when-to-use and how-to-proceed guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses significant behavioral traits: the output format is decimal-string rupees, the summary covers the full filtered set and ties the spreading reconciliation, no target-level split or source transactions are returned, page tokens are source-pinned and expiration behavior is described, and run-state fields (known_stale, not_assessed) are explained. This far exceeds the annotation coverage and gives the agent a precise mental model of the tool's 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?

The description is compact and information-dense. It leads with 'MANAGEMENT data class' and a clear statement of purpose, then efficiently layers in the data model, filtering, paging, summary behavior, and run-state semantics across four sentences. Every sentence adds unique information, and there is no filler or repetition of 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 complex tool with 6 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains the output grain, the arithmetic relationship of figures, filtering options, paging behavior, what data is excluded, and how to interpret run-state flags. It leaves no major ambiguities about what the tool returns or how to handle pagination edge cases, making it fully self-sufficient for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The tool description adds semantic value by explaining the data context (books + spreading = MIS, decimal-string rupees), which helps understand parameters like min_abs_mis. It also clarifies the interaction between filtering and paging, and reinforces the source-pinned nature of page_token. While it doesn't describe each parameter individually, the holistic context meaningfully aids parameter understanding, so a 4 is justified.

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 ('Read') and a specific resource ('the current persisted allocation run at account grain'), and explicitly clarifies the data model (books + spreading adjustment = MIS figure). It distinguishes itself from the sibling get_allocation_target_figures by noting that no target-level split is returned, making the purpose unmistakable.

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 description provides clear context for when to use this tool: it reads management allocation data at account grain, supports filtering before paging, and clarifies that target-level splits are excluded. It also gives explicit paging guidance (restart at page 1 if source_changed) and explains how to interpret run-state flags. However, it does not name a direct alternative tool or state explicit 'when not to use' conditions, 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, but the description adds valuable behavior: 'the signed page_token is source-pinned, so restart at page 1 if source_changed' and 'Target labels are cost-centre names as of the run and current profit-centre names'. This exceeds the annotation-only safety profile.

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 sentences, front-loaded with 'MANAGEMENT data class' and the grain. No filler—each sentence adds unique information: data grain, filtering patterns, pagination caveat, and label semantics/exclusions.

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 8 parameters and no output schema, the description covers the essential context: grain, amount format, recommended filters, pagination behavior, and what is not returned. This gives an agent enough to invoke correctly and set expectations.

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 parameters are documented. The description adds meaning beyond the schema by explaining how to use enum values (allocation_sources, target_types) and the page_token behavior ('source-pinned, restart at page 1 if source_changed'). Minor gap: doesn't elaborate on min_abs_amount or account_name_patterns, but the schema covers them.

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: 'Read the current persisted allocation run at account × target × source × mode grain, with decimal-string allocated amounts.' It clearly distinguishes from the sibling get_allocation_account_figures by specifying the target grain and returned data format.

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 explicit when-to-use guidance: 'For step-down, filter allocation_sources=["step_down"]; for profit centres, filter target_types=["profit_centre","sub_profit_centre"]' and 'Use filters before paging'. It also states exclusions ('no owners, descriptions, source transactions, or recomputation are returned'), making it clear when NOT to use this tool.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses substantive behavioral traits: amounts and FX rate are decimal strings, page_token is source-pinned and requires restart on source_changed, no cross-line grand total is exposed, and identity-related fields are omitted. This goes well beyond what annotations provide.

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 information-dense but well-structured: it opens with the core purpose, then covers data types, pagination/filtering, a caveat about grand totals, and exclusions. Every sentence contributes unique value, and the text is front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters and no output schema, this description is notably complete. It explains the return contents (header, P&L tree, cells), pagination/filtering semantics, and important limitations (no grand total, no identity fields), giving an agent enough context to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 8 parameters have schema descriptions (100% coverage), setting a baseline of 3. The description adds extra meaning by mentioning filter dimensions ('months, lines, centres, or inference') and the source-pinned page_token behavior, which clarifies how parameters interact beyond the schema's individual property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Read') and a distinct resource ('one versioned budget'), and it enumerates the returned components (identity-free header, pinned P&L tree, filtered/paginated cells). It differentiates itself from sibling get_* tools by focusing on budget data and including a data-class qualifier ('MANAGEMENT').

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 description provides context about what the tool returns and notes exclusions (no people/ownership/approval identities), but it does not explicitly indicate when to use this tool versus alternatives like list_budgets or get_tb_rows. Usage guidance is implied by the tool name and the first sentence, but no explicit alternatives or exclusions are 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 already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond: it explains the sealed-run persistence, page-token fingerprinting and restart requirement, stale-run disclosure, and the exact return format (single decimal-string amount per line, signed for CFS). This significantly enriches the agent's understanding of the tool's 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?

The description is dense but every sentence contributes unique information: purpose, response shape, persistence behavior, pagination requirements, limitations, and missing data. It is front-loaded with the core purpose and then layers behavioral details without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the absence of an output schema, the description covers the response format, what is not returned, pagination and change detection, and feature availability. It provides sufficient context for an agent to select and invoke the tool correctly without needing additional documentation.

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% with useful parameter descriptions. The description adds extra meaning for parameters like page_token (source-fingerprinted) and statement (section-natural vs signed cash movement), but most parameter semantics remain in the schema. This is above the baseline 3 due to the additional context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Read') and resource ('sealed consolidated statements'), enumerates the statement faces (P&L, balance-sheet, cash-flow), and scopes by periodicity/period. It distinguishes itself from sibling tools by the 'CONSOLIDATED data class' label and detailed behavioral characteristics.

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 description provides clear context on when the tool is appropriate, including limitations (cash-flow only for all-domestic groups, no foreign currency). However, it does not explicitly name alternative tools or state 'use this instead of X', so it stops short of full exclusion guidance.

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

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

The description discloses important non-obvious behaviors beyond annotations: the tool re-reads stored workbook, approval is single-use/expires in 15 minutes, tied to exact version/connection/member, and will cause finalise_statement to refuse if anything changes. It also explains semantics of capture_live_diverged_message and 'could not be evaluated' controls. No contradictions with annotations (readOnlyHint false is consistent with approval issuance).

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 long but every sentence carries actionable guidance. It is front-loaded with the purpose and includes critical operational warnings (do not poll, show every row). Some redundancy exists (e.g., 'Do not summarise warnings away' vs 'SHOW YOUR USER EVERY ROW'), but the density of unique, important instructions justifies the length. Minor structural improvements (e.g., bullets) would make it a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must explain return values. It does so comprehensively by enumerating the key content: gates that must be green, warnings, empty input cells, unevaluated controls, capture_live_diverged_message, and the approval itself. It also covers edge cases like lack of permission and version changes. This is complete for a tool with this complexity and criticality.

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 3 applies. The description does not add parameter-level syntax or format details beyond what the schema already provides. It relates on_behalf_of to the approval being tied to the named member, but this is behavioral context, not parameter semantics. The schema already instructs to ask the user for the email, so no further explanation needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Read the full finalisation state of one statement version, and get the approval finalise_statement needs,' using a specific verb, resource, and distinguishing it from the sibling finalise_statement. It also clarifies this is the pre-finalisation check, which differentiates it from other get* 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?

Provides explicit usage instructions: 'Call it ONCE immediately before finalising — it re-reads the stored workbook, so do not poll it.' It also tells the agent to show every row to the user before finalising, and explains behavior if connection is not permitted. This gives clear when-to-use and what-to-do guidance, and indirectly distinguishes from finalise_statement.

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 valuable context by specifying what the guide contains (OAuth/API key, assistant capabilities, statement-as-data, guarantees/limits, tool list) and that it serves as canonical documentation. This goes beyond the annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact: two sentences, front-loaded with the tool's purpose, followed by a structured list of contents and a direct usage instruction. Every word earns its place, with no redundancy or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is fully sufficient. It explains what the guide covers, why to use it, and frames it as the canonical source for answering user questions, making it complete in context.

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 has zero parameters, which sets a baseline of 4. The description does not need to explain parameters and instead clarifies the tool's scope, maintaining 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?

The description uses a specific verb ('Get') and names a concrete resource ('the Datavrn agent guide'), then lists its contents. It clearly distinguishes from sibling tools that perform data operations, making this uniquely about documentation.

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 description explicitly states when to use it: 'Call this to answer a user's questions about how Datavrn works from canonical documentation instead of guessing.' It provides clear context but does not mention any exclusions or alternative tools, so it earns 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?

The description significantly expands on the annotations. While readOnlyHint=true and destructiveHint=false are useful, the description adds critical behavioral details: the asynchronous nature of jobs, that 'queued' for a few minutes is normal, that the tool returns a user-safe error reason on failure, and that the agent should keep polling. This is far beyond the annotations and helps the agent understand the tool's runtime 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?

The description is structured with a clear first sentence stating the core action, followed by failure handling, then queued-status behavior, and a final clause on when to escalate. Each sentence earns its place, and the length is justified by the need to prevent misinterpretation of the queued status. There is no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description adequately covers the essential return information: statuses (succeeded, failed, queued), the presence of an error reason on failure, and the attempts count implied by '0 attempts'. It does not enumerate all possible statuses or include other fields, but for a polling tool, it provides sufficient context for an agent to act correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage for the single parameter 'job_id', stating that it is the job id returned by generate_schedule_iii. The description does not add any additional semantic detail about the parameter itself. Therefore, the baseline of 3 is appropriate, as the schema does the heavy lifting and the description adds no extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Poll a background job by id until status is succeeded or failed.' It identifies the specific resource (background job) and action (poll by id), and it distinguishes this tool from siblings by focusing on generic background job status rather than specific entity statuses. The description also clarifies the end condition, which fully captures the tool's purpose.

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 description gives extensive usage context, including polling frequency (every ~30–60s), how to interpret the 'queued' status (normal initially), and how to communicate results to the user (show error reasons, reassure user). However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5 but provides clear enough context for when it should be used.

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 provide readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral detail: it returns people's names, profit-sharing ratios, amounts, and the total of ratios. It also explains why the total is returned (Datavrn warns only when at least two rows carry a ratio), which goes beyond the structured annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet complete, with the core purpose in the first sentence and all additional sentences carrying actionable context (usage before save, return contents, and ratio-total behavior). No filler or repetition of schema details.

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 tool with no output schema, the description adequately covers the return contents and why the total is included. It also ties into the save sibling. Minor gaps like pagination behavior are already covered by the schema's limit/offset descriptions, so the overall context is strong.

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 each parameter has a thorough schema description (e.g., account_kind maps 'capital' to Note 3a and 'current' to Note 3b). The tool description reinforces the Note 3a/3b framing but does not add significant parameter-level meaning beyond the schema, so 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 clearly states the tool reads the partner or owner capital schedule (Note 3a and Note 3b), with a specific verb ('Read') and resource. It differentiates from siblings such as save_partner_capital by explicitly framing itself as the read-before-write companion.

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 guidance is explicit: 'Call it before save_partner_capital so you can show your user what is on file and what your change would do.' It explains why reading first is necessary because the save replaces the whole section, and even discusses the Datavrn total-ratio warning behavior.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds valuable behavioral context beyond that: it explains the default period selection logic (not necessarily the newest period, resistant to early future uploads), states that deep links require a Datavrn login, and clarifies the per-entity row structure. This exceeds the minimal bar.

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 three sentences, front-loaded with the core purpose, followed by parameter guidance and a note about deep links. Every sentence contributes essential information without redundancy or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with one optional parameter and no output schema, the description is complete: it explains what is returned (one row per entity, with specific blocking fields), how the default period is chosen, and that deep links require login. No critical behavior is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers period_label with a clear description (100% coverage), so the baseline is 3. The description adds extra nuance about the default period selection ('not necessarily the newest — one entity uploading a future period early will not flip the board') and the optional omit behavior, which provides value 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 uses a specific verb ('Answer') and resource ('what's left to do? across every entity you can see'), clearly stating the tool's purpose. It distinguishes itself from sibling tools by emphasizing cross-entity aggregation of Schedule III blocking factors, which is a unique scope.

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 description provides clear context on when to use the tool (to see pending work across entities) and how to invoke it (pass period_label or omit for default). It does not explicitly name alternative tools or say when not to use it, so it stops short of the highest level of guidance.

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

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

Beyond the readOnlyHint annotation, the description adds non-obvious behavioral details: it will never mark capture complete, and exception output is deliberately limited to rule/severity/count without sensitive account data. This sets accurate expectations for side effects and data scope.

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 dense, informative sentences with no filler; each clause earns its place. Slightly heavy on domain jargon like 'bounded per-version control summaries' may impede quick comprehension, but overall it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given its read-only nature and rich annotations, the description covers tool outputs, non-side-effect behavior, and output limitations. It lacks only a full return structure, which is acceptable without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no parameter-specific semantics. The baseline of 3 applies because the schema already fully documents each parameter's meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly positions this as the central state tool for Schedule III, enumerating specific components (grouping progress, capture answers, versions, blockers, control summaries). This distinguishes it from sibling tools like get_statement_figures or get_setup_status by framing it as the holistic workspace view.

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 'Call this to know what is left before finalising', providing a clear when-to-use scenario. It does not name alternative tools or exclusions, but the context is sufficient for selecting this over other read-only 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 already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: it only reports status (counts, names, what is done), never returns a figure or balance, and explains that web_only steps require login. It also discloses that on an empty organization it returns the create-first-entity step. There is no contradiction with the annotations.

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 long but every sentence carries actionable information: two calling modes, step statuses, narration instruction, web_only caveat, and scope limitation. It is front-loaded with the use case. The length is justified by the tool's complexity; there is zero fluff.

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 fully explains return semantics: org vs entity views, step statuses, tool links, and the narration rule. It even cross-references get_statement_figures to clarify what the tool does NOT return. Given the tool's dual-mode nature, this is complete and leaves no critical ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the single parameter well (omit for org view, include for entity path). The description reinforces this and adds the step sequence and the 'create entity' fallback, deepening the agent's understanding of how the parameter affects output. Since schema coverage is 100%, this extra context raises it above a baseline 3.

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 opens by naming the exact user questions ('how do I get started?', 'what do I do next?') and states it 'Returns where they are in the journey... and the ONE next step to take.' This clearly identifies the tool's purpose (reporting setup status) and distinguishes it from sibling tools like get_pending_work or generate_schedule_iii.

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 description gives explicit when-to-use guidance (user lost during setup) and a precise two-call protocol: first without client_id, then with one entity's client_id. It also instructs the agent to narrate one step at a time, warns against claiming to perform web_only steps, and points to get_statement_figures for figures. This is exemplary usage guidance.

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

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

Beyond the readOnlyHint annotation, the description adds extensive behavioral detail: view-specific output semantics, decimal-string rupees, invariant summary figures, source-pinned page_token behavior, and the meaning of warning states. This significantly aids the agent in interpreting results and 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?

The description is concise yet information-dense, with every sentence contributing unique value. It is front-loaded with the core purpose and uses a logical flow (purpose, views, data format, pagination, warnings). No redundancy or fluff.

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?

Despite the absence of an output schema, the description covers critical contextual aspects: view contents, pagination semantics, data type, summary behavior, and disclosure states. This is a complex tool with 7 parameters, and the description provides enough context for the agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description mostly reinforces schema information (e.g., adjust view requires account_id, page_token source pinning) and adds output-related context rather than new parameter depth. It does not materially elevate parameter understanding 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 clearly states the tool reads the persisted books-to-MIS spreading reconciliation, using a specific verb and resource. It explicitly distinguishes from a new allocation run and explains the two view modes, making its purpose unambiguous relative to sibling 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?

The description provides clear context: it is for reading the persisted reconciliation, not a new allocation run, and explains when to use accounts vs adjustments view. It lacks explicit alternatives by name, but the exclusion and view guidance are sufficient.

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 readOnlyHint, the description discloses that it never recomputes from live books, null verdicts mean UNKNOWN (never a pass), old versions return available:false with a specific reason, and amounts are decimal strings in rupees. These behavioral traits add significant context beyond annotations and do not contradict 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?

Although lengthy, every sentence provides a distinct, non-redundant fact (return list, null semantics, no live recomputation, version behavior, retry guidance, sibling alternative, amount format, interpretation responsibility). The description is front-loaded with the primary purpose and is appropriately structured for the tool's complexity.

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 thoroughly enumerates return values, edge cases (unavailable versions), and data types, covering the major aspects of a complex read tool. It even notes 'bounded exception counts' and matches the workbook exactly, leaving no significant 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 coverage is 100% (all four parameters described), so baseline is 3. The description's version phrase ('the latest unless you pass a specific version') merely restates the schema's 'omit for the latest' and adds no new meaning. No other parameter is elaborated beyond 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 opens with a specific verb+resource ('Read a generated Schedule III statement's figures') and enumerates the returned components (balance-sheet/P&L faces, tie verdicts, unclassified count, notes, exception counts, control changes). It explicitly distinguishes from a sibling tool by directing note line-by-line breakdown to get_statement_notes.

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 indicates this tool reads figures from a generated version, provides an alternative (get_statement_notes for note breakdowns), and instructs how to handle old versions ('generate the statement again, read the latest version, then retry'). This constitutes explicit when/alternative guidance.

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

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

Beyond the readOnly and non-destructive annotations, the description discloses line kinds ('component', 'subtotal', 'header'), warns against double-counting subtotals, explains fixed-asset block structure, details pagination (lines_page, has_more_lines), the too_large flag, decimal strings, and deterministic engine output. This is extensive behavioral context far exceeding annotation value.

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 yet front-loaded with the core purpose, then systematically covers line kinds, blocks, pagination, and data format. Every sentence delivers distinct, actionable information without redundancy, making it easy for an agent to parse and apply.

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 response features (line kinds, totals, pagination fields, too_large flag) and edge cases like double-counting subtotals and single large notes. It fully equips an agent to safely interpret and consume the tool's output across normal and paginated scenarios.

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?

Although schema coverage is 100%, the description adds operational meaning: note_numbers can be omitted for all notes, lines_page should be fetched until has_more_lines is false, and how note_index from get_statement_figures feeds into note_numbers. This deeply enriches the schema's basic parameter descriptions.

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 opens with a specific verb and resource: "Read the line-by-line breakdown of a generated statement's notes," and clearly states what is included (current/prior-year amounts, note total). It also distinguishes from siblings by referencing get_statement_figures' note_index and the note-level scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit use cases are given ("Use this to answer 'what's in Other Expenses?'...") and it directs users to get_statement_figures for note_numbers. However, it does not explicitly state when not to use this tool or name alternative tools for higher-level summaries, missing the 'when-not/alternatives' part of the 5-level criteria.

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 mark read-only and non-destructive, but the description adds valuable behavior: rows may not tie to a generated version after re-upload, amounts are decimal strings in rupees, output is deterministic, and pagination behavior. These go beyond annotations.

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 every sentence earns its place: purpose, filtering guidance, pagination, data freshness caveat, amount format, and interpretation responsibility. It is well-structured and front-loaded.

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 covers the key output fields (account name, debit, credit, totals, note), filters, pagination, and data semantics. It is complete for an agent to decide and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage, so baseline is 3. The description enhances this by providing examples for name_patterns, side, and min_abs_balance, plus clarifying pagination defaults, adding meaningful context 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 states a specific verb+resource+scope: 'Read the SOURCE DATA behind a statement: the trial-balance rows (account name, debit, credit) as landed for a period, BEFORE grouping'. It clearly distinguishes from statement figures and sibling tools like get_statement_figures.

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 to 'PREFER FILTERS over fetching everything', gives a concrete example (wrong-side cash accounts), and notes the 'CURRENT live rows' vs frozen statement figures, indicating when not to use this tool. It also contrasts with statement figures.

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 aligns by saying 'Read'. It adds value by listing the specific data returned, which goes beyond the annotation. It does not mention side effects, but for a read-only tool this is sufficient.

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 two sentences, front-loaded with the action and resource, and every sentence contributes. There is no redundant information or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one parameter and no output schema, the description fully covers what the tool returns and when to use it. No additional behavioral context seems necessary.

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 upload_id parameter already has a clear description ('returned by upload_trial_balance'). The tool description adds no additional parameter semantics, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads an upload session and enumerates exactly what it returns (status, header row/columns, confirmed mapping, validation outcome). The verb 'Read' plus resource 'upload session' is specific and distinct from siblings like get_upload_link_status.

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 line 'Use to check what a staged upload still needs' provides clear usage context. However, it does not explicitly mention alternatives or when not to use this tool, so it falls 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, and the description adds meaningful behavioral context by enumerating the three states and what they return (e.g., upload_id for uploaded). It doesn't mention edge cases or rate limits, but for a simple read-only status check, this is adequate.

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 two sentences, front-loaded with the core purpose, and every clause adds value. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple status-check tool with strong annotations and a single well-documented parameter, the description fully covers the states and next actions. The lack of an output schema is acceptable here because the description verbally explains what is returned for each state.

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 single parameter link_id is documented in the schema with 'The link id returned by create_upload_link.' The description does not add further parameter-level detail beyond that, but since schema coverage is 100%, a baseline score of 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 uses a specific verb 'Check' and clearly identifies the resource (upload link) and its states (pending, uploaded, expired). It also distinguishes itself from sibling tools by referencing get_upload and create_upload_link, making its purpose unmistakable.

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 description explicitly states when to use this tool ('Poll after the user says they uploaded the file') and provides action guidance for each possible state, including alternatives like continuing with get_upload or creating a new link via create_upload_link.

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=true and destructiveHint=false. The description significantly expands on this with deep behavioral details: null semantics ('null actual or variance means unavailable, never zero'), rollup behavior ('whole-report unfiltered rollups and no cross-side grand total'), privacy filtering ('withholds internal notes and may redact structured PII'), and pagination semantics ('source-pinned, so restart at page 1 if source_changed'). This goes far beyond the annotations and is highly informative.

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 a dense, well-structured paragraph that front-loads the core purpose ('MANAGEMENT data class. Read the existing budget-or-prior variance report') and then packs high-value edge-case details into a compact series of clauses. Every sentence contributes distinct information (nulls, rollups, explanations view, paging) without redundancy or 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?

This is a complex tool with 8 parameters, two views, pagination, and subtle data semantics, and there is no output schema. The description covers critical operational details: null handling, rollup behavior, explanation-view redaction, and paging restart logic. It is thorough enough that an agent could invoke this tool correctly with minimal additional inference, making it effectively complete for its complexity.

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 each parameter has a baseline description. However, the tool description adds meaningful semantics about how parameters interact: filters affect rows and filtered grain counts, and page_token is source-pinned. This goes beyond individual parameter docs, enriching understanding of view, line_codes, cost_centre_ids, and page_token. Given the high schema coverage, a 4 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 opens with 'Read the existing budget-or-prior variance report for a month; it never recalculates it.' This clearly identifies the action (read), the resource (existing variance report), and the scope (budget/prior, monthly). It distinguishes this from sibling read tools like get_budget or get_statement_figures by specifying the variance-report resource and its read-only, non-recalculating nature.

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 description establishes usage context by stating it reads an existing report and never recalculates, implying it should be used when a pre-computed variance report is needed. It also provides practical guidance: 'Filter lines or centres before paging' and the page_token restart condition. However, it does not explicitly name alternative tools or state when not to use it, so it falls 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?

The description adds substantial behavioral context beyond annotations: short-lived signed URL, ~10-minute expiry, no login required, immutable bytes with integrity hashing. These details help the AI understand the tool's behavior without needing to invoke it. No contradiction with the readOnlyHint=true annotation.

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, front-loaded with the core purpose, no redundant phrasing. The second sentence adds essential usage and behavioral details without waste. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains what the tool returns (a URL) and gives key attributes (short-lived, no login, immutable). It does not specify the exact response format (e.g., JSON field name), but for a low-complexity tool with no output schema, this covers the essential context. Slight gap in not mentioning any error conditions or prerequisites.

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 input schema already provides 100% coverage with descriptions for client_id and snapshot_id, referencing list_clients and list_snapshots. The description adds minimal meaning for snapshot_id ('frozen workbook version') but does not elaborate on parameter syntax or format. Baseline of 3 is appropriate given high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Mint a short-lived signed URL for a frozen workbook version (the Excel file).' The verb 'mint' is specific and the resource (workbook download) is unambiguous. It distinguishes itself from sibling download/upload tools by focusing on the frozen workbook version download.

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 description provides clear context: 'Give the URL to your user to open in a browser — it needs no login and expires in about 10 minutes.' This implies the tool is for user-facing download of a frozen workbook, but it does not explicitly mention alternatives or when not to use. The context is clear but lacks exclusions.

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 include destructiveHint=true, but the description adds critical behavioral context: it refuses on warnings unless acknowledge_warnings=true, requires explicit user consent for each warning, and never auto-acknowledges unseen warnings. This goes well beyond the structured fields and clarifies the destructive action's safeguards.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, purpose first, then warning behavior, then return value. No redundancy or 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?

The description communicates the commit action, warning refusal policy, user-consent requirement, and return outcome. It lacks detail on confirm_merges semantics and any side effects beyond 'ingestion outcome,' but given the absence of an output schema and the succinct structure, it is largely sufficient. A 5 would require covering the confirm_merges parameter or more explicit post-conditions.

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 only 33% (only upload_id described). The description adds meaning to acknowledge_warnings by explaining its role in overriding warning refusal. However, confirm_merges remains entirely unexplained; its schema shows prior_account_id and new_name but no semantic description. This partial compensation yields an average score.

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 opens with a specific verb and resource: 'Commit a validated upload into the entity’s books.' This clearly distinguishes it from sibling tools like upload_trial_balance (which likely uploads but does not commit) and the confirm_* tools (which handle pre-ingest mappings).

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 description implies usage after validation, stating it commits a 'validated upload' and that warnings block ingestion until acknowledged. It does not name alternative tools explicitly but provides clear context: this is the final ingestion step. No exclusions or when-not-to-use are given, so not 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. The description adds substantial context: it is 'status-only', never returns rupee amounts, returns deterministic suggestions, and imposes presentation rules (grouping by confidence tier, exact counts, flagging medium/low rows, and avoiding the word 'pending'). This goes well beyond the annotations and clarifies the tool's behavioral safety and output expectations.

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, front-loaded with the primary purpose. The second sentence packs many required presentation rules, which is dense but each clause earns its place. It could be broken into bullet points for readability, but it is efficient and clear.

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, so the description takes on the burden of explaining return values: account names, types, target names, confidence, reasons, balance-bearing booleans, and the two completion counts. It also covers usage context. Gaps remain (e.g., ordering of results, definition of confidence tiers, pagination behavior) but the core information is present.

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%, with every parameter documented (e.g., client_id, page, page_size, name_patterns, unmapped_only, balance_bearing_only). The description does not add additional parameter-level meaning beyond what the schema already provides, and the baseline is 3 when the schema carries the burden.

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 starts with a specific verb+resource: 'Review account-to-cost-centre mapping status and deterministic suggestions'. It clearly distinguishes from sibling tools like confirm_centre_mappings or list_grouping_suggestions by emphasizing 'status-only' and listing exactly what is returned.

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 description clearly sets the context: use this to review mapping status before confirming, and it explicitly states what data is NOT returned (no amounts). However, it does not name alternative tools or explicitly say when not to use it, so it stops short of a full 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 provide readOnlyHint=true, but the description adds substantial behavior beyond that: ordering by period/version/run id, page_token pinning and source_changed handling, current_only semantics (not freshness), stale warnings ('never a claim that the source is fresh'), and absence of raw reasons. This is rich context and fully transparent.

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 dense sentences, each adding new information: classification, purpose, money format, ordering, pagination semantics, stale warnings, and exclusion of raw reasons. Front-loaded with purpose and 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?

Despite no output schema, the description fully covers the operational semantics: ordering, pagination with source pinning, current_only meaning, stale warning interpretation, and data format (decimal-string rupees). It is complete for a read-only list tool and handles edge cases.

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?

All 5 parameters are fully described in the schema (100% coverage), so the baseline is 3. The description elevates this by adding deeper meaning for page_token ('pinned to the complete filtered source... restart if source_changed') and current_only ('latest generated version, not source freshness'), which goes beyond the schema's descriptions.

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 opens with a specific verb-resource pair ('Discover persisted allocation runs') and immediately clarifies scope ('conservation heads') while explicitly stating what it does not do ('does not generate or recompute allocation'). This strongly distinguishes it from generation tools like generate_schedule_iii.

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 indicates when to use (discover persisted runs) and includes an explicit exclusion ('does not generate or recompute allocation'), but it does not name alternative tools or provide broader when-to-use guidance beyond this scope. The context is clear but not exhaustive.

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=true, destructiveHint=false), the description adds meaningful behavioral context: money-valued fields are decimal strings, page_token is pinned to the complete filtered source, and restart at page 1 if source_changed. These details are not present in annotations and enrich the agent's understanding.

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 sentences, each carrying distinct information: data class, purpose, data format, pagination, and scope exclusions. The 'MANAGEMENT data class' phrase is somewhat cryptic, but the description is not bloated and front-loads the core purpose.

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 list tool with 5 parameters and no output schema, the description covers purpose, pagination behavior, data format, and exclusions, providing a solid mental model. It does not explicitly describe the full response structure but implies the return contains budget ids and versions, which is adequate.

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 covers all parameters (100%), but the description adds usage semantics: 'Filter status or fiscal-year start before paging' and explains the page_token's pinning behavior. This goes beyond the schema's individual parameter descriptions.

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?

Description explicitly states 'Discover budget ids and versions' and 'lists budget headers only', clearly identifying the resource (budgets) and action (list/discover). It distinguishes itself from sibling tools like get_budget by scoping to headers only and excluding cells, approvals identities, and recalculated budgets.

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 clear usage context: filter status or fiscal-year start before paging, and explains page_token pinning with restart guidance if source_changed. It notes what the tool does NOT list, implying alternatives, but does not explicitly name sibling tools like get_budget.

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 safe read nature is covered. The description adds behavioral context by stating the returned data (entity id and name) and the credential-scoping behavior, which is useful beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary action and immediately followed by the key usage instruction. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless read-only list tool, the description fully covers purpose, usage, return format, and relationship to other tools. No output schema exists, but the description explicitly states what is returned (entity id and name), making it 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?

The tool has zero parameters, so schema coverage is 100% by default. The description adds meaningful context about the resource being listed and the return value, fulfilling the baseline for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('List') and resource ('entities (companies) this credential can work with'), and explicitly distinguishes the tool's purpose by explaining it resolves the client_id needed by other tools. This differentiates it from sibling tools like create_client or list_budgets.

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 instructs 'Call this first to resolve the client_id every other tool needs,' giving concrete when-to-use guidance and positioning it as a prerequisite step. This is strong usage direction beyond what annotations provide.

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 meaningful context beyond annotations: it is 'status-only', returns only names/kinds (never rupee amounts), and advises informing the user about the existing structure before suggesting changes. This enriches the behavioral profile without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: primary action, workflow context, and behavioral caveat. Front-loaded with the verb+resource, no filler, and well-structured for quick comprehension.

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?

Despite no output schema, the description explains the return content (names and kinds, no amounts) and covers purpose, usage, and user interaction guidance. Combined with detailed schema and annotations, the tool is fully contextualized for an agent to invoke and interpret results.

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%, with each parameter (client_id, page, page_size) fully described in the schema. The description adds no parameter-specific detail beyond what the schema provides, so 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 opens with a specific verb+resource ('List the cost centres for an entity') and distinguishes from siblings like list_profit_centres by clarifying it returns names and kinds only, never rupee amounts. The purpose is unambiguous and clearly scoped.

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 when to use it ('before proposing account mappings') and what to do with the results (group by target name, distinguish operating vs support, explain structure before suggesting changes). It does not name alternatives or provide explicit 'when not to use' exclusions, but the context is clear and actionable.

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 indicate read-only and non-destructive behavior. The description adds substantial behavioral context: deterministic rules (no AI), Datavrn never auto-applies, pagination behavior, summary counts remain whole-population when filtering, and return format. No contradiction with annotations.

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 and front-loaded, but somewhat long (~170 words). Every sentence adds value, though some phrases like 'a single blanket approval is not a review...' could be tightened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (8 params, pagination, confidence tiers, confirmation workflow) and no output schema, the description is remarkably complete. It explains return format, pagination, filtering strategy, and the confirmation flow, offering sufficient context for correct tool 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 already covers 100% of parameters, so baseline is 3. The description adds usage semantics for confidence (fetch tier by tier), include ('confirmed' shows already-grouped), and has_balance (call out balance-bearing rows), which goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists ungrouped accounts with deterministic grouping suggestions, using a specific verb and resource. It distinguishes itself from the sibling confirm_groupings tool by explicitly noting that suggestions are never auto-applied.

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 explicit usage guidance: present suggestions grouped by confidence, call out low-confidence rows, confirm only via confirm_groupings, and fetch tier by tier instead of all at once. It also tells when to use include='confirmed'.

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 indicate read-only and non-destructive behavior. The description adds meaningful context by specifying that only periods with a live Trial Balance are listed and that the output consists of period IDs used by specific downstream tools. This goes 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 two sentences: the first leads with the primary action and scope, the second clarifies the output and consumers. Every word adds value, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list operation with one parameter and no output schema, the description fully covers purpose, the condition (live Trial Balance), and return value (period IDs). Naming the downstream tools provides integration context, making the description complete on its own.

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 input schema fully documents the single parameter client_id, including its type and derivation ('from list_clients'), so the description need not add further detail. The description does not mention parameters at all, which is acceptable given the schema coverage is 100%.

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 ('List'), a clear resource ('reporting periods for a Schedule III statement'), and a distinguishing condition ('periods with a live Trial Balance'). It also names downstream consumers (get_schedule3_workspace, save_py_values, generate_schedule_iii), which differentiates it from other list_* 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?

The description implies when to use the tool: before preparing a Schedule III statement, to obtain valid period IDs. It explicitly names the tools that consume these IDs, giving clear workflow context. However, it does not explicitly state when not to use it or mention alternatives, so it falls just 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. The description adds meaningful context: 'It returns names and hierarchy, never rupee amounts,' which clarifies the return scope without contradicting the annotations.

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 concise sentences, each earning its place: purpose, usage context, and behavioral caveat. No redundancy or 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?

Given the simple read-only list tool, the description plus schema fully cover what an agent needs: return type (names/hierarchy), non-financial nature, and pagination parameters. No output schema exists, but the description adequately conveys return content.

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. The description doesn't add parameter-specific details beyond the schema, but it doesn't need to; the schema already documents client_id, page, and page_size thoroughly.

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 opens with 'List the profit centres for an entity', a specific verb+resource with scope. It further distinguishes itself from siblings by noting it's used 'before a user confirms any explicit mapping', clarifying its role versus confirmation/mutation 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?

It gives clear when-to-use context: 'Use this to explain available targets before a user confirms any explicit mapping.' However, it doesn't explicitly name alternative tools or state when not to use it, though the phrase implies it precedes confirm_centre_mappings.

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 readOnlyHint and destructiveHint annotations, the description discloses that the tool returns names, line labels, confidence, reasons, and balance-bearing booleans but never debit, credit, balance, or any rupee amount. It also clarifies the output is deterministic and instructs not to label the two counts as pending, giving meaningful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the purpose and safety scope stated in the first two sentences. The final sentence adds useful presentation guidance but is somewhat opaque, especially the do not call either count pending clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates well by enumerating the key returned fields and count semantics. It does not fully specify the response structure or pagination behavior, but the schema already covers paging parameters and the description provides enough for a reasonable agent to invoke and interpret the 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?

Schema description coverage is 100 percent, so the parameters are already well documented. The description adds only the general notion of entity and reporting period, which does not materially improve on the schema, justifying the baseline score.

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 uses a specific verb, Review, and identifies the exact resource: reporting-line classification status and deterministic suggestions for an entity and reporting period. The explicit status-only framing clearly distinguishes it from sibling confirmation and mutation 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?

The read-only, status-only description makes the intended review use case clear and implicitly separates it from confirm_reporting_lines and other mutation tools. It does not explicitly name exclusions or alternatives, so it falls slightly short of a perfect usage-guidance score.

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. The description adds useful behavioral context: versions are 'frozen' (immutable), ordered 'newest first', and include 'unclassified count at build time'. This exceeds the annotation baseline without contradicting it.

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 sentence packs all essential information: what is listed, the scope, ordering, and key fields included. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully enumerates returned fields (period, template, unclassified count) and ordering. It may omit a version identifier/timestamp, but for a straightforward list tool with two parameters, this is largely sufficient.

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 both parameters have clear descriptions (client_id source from list_clients, template_id as a filter). The tool description aligns with these but does not add additional semantic nuance beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and specifies the exact resource ('frozen Schedule III workbook versions') with scope ('for an entity') and ordering ('newest first'). This distinguishes it clearly from sibling list tools like list_clients or list_budgets.

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 description implies usage for retrieving a client's frozen version history, but it does not explicitly mention when to use this tool versus alternatives such as get_workbook_download or get_schedule3_workspace. No exclusions or alternative tool references are provided.

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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral nuance: the captured flag distinction, the two meanings of differs_from_prior, the definition of 'last year' as the same month one year earlier, and the meaning of prior_period_found. It also warns about a critical trap ('Warn your user about that second case explicitly') that annotations cannot convey. No contradiction with annotations.

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 long but front-loaded with the core purpose in the first sentence. It then delivers critical rules in a structured, information-dense manner. Every sentence serves a purpose, but the overall length is substantial and could be tightened. It earns a 4 rather than a 5 due to verbosity.

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 full burden of explaining return values and important nuances. It covers the listed fields, summary counts (changed_total, not_carried_forward_total, differs_from_prior_total), the definition of 'last year', prior_period_found semantics, and finalisation blocking. This is more than adequate for an agent to understand and act on the tool's results.

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 input schema provides 100% coverage with descriptions for all five parameters (client_id, template_id, period_id, limit, offset). The tool description does not add parameter-specific meaning beyond that, but it does reference statement context and prior-period semantics which indirectly relate to period_id. Since schema already does the heavy lifting, a 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 opens with a specific verb+resource+scope: 'List every Significant Accounting Policy and Other Regulatory Information affirmation for this statement, with the text that will print, whether a template choice is still unresolved, and what was answered LAST YEAR.' This clearly distinguishes the tool from siblings like save_accounting_policies or finalise_statement, making the purpose unmistakable.

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 description gives strong contextual guidance on when to use it: 'An unresolved choice blocks finalisation, so work through them with your user before generating the version you intend to finalise.' It also warns about the silent-replacement scenario. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to decide.

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

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

The description discloses non-destructive behavior ('Nothing is deleted'), the audit trail, and the side effect of invalidating approvals. This goes well beyond annotations (readOnlyHint=false, destructiveHint=false) and provides critical operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence adds a distinct behavioral or usage detail; the main action is front-loaded. The length is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description thoroughly covers side effects, invalidation, and alternative actions. However, it does not mention the tool's return value or what happens on error or when no answer exists, which is a small gap given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 40%. The description adds context about who recorded/withdrew and the invalidation effect, which helps with on_behalf_of, but period_id and template_id lack schema descriptions and are not explained in the description. The enum for capture_kind is helpful, but overall the description does not fully compensate for the coverage gap.

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 first sentence clearly states 'Withdraw a recorded capture answer or review confirmation', combining a specific verb and resource. It also explains the effect on statement readiness, distinguishing it from confirm/save 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?

Provides explicit context: if a generated version is not wanted, the tool alone won't prevent finalisation; instead, answer again and generate fresh. It also describes the impact on get_finalise_readiness and finalise_statement, making it clear when to use this tool vs alternatives.

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 far beyond the annotations (destructiveHint=true) by detailing the complete replacement semantics: 'this replaces all of Note 2, so any title you leave out of this call is removed.' It also discloses approval requests, refusal of unrecognized headings, change-in-policy disclosure requirements, handling of captured flags, and the need to generate a fresh version after changes. No contradiction with annotations.

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 long and contains redundancy, such as instructing to call list_statement_policy_choices first twice. While all content is relevant and the purpose is front-loaded, the text could be tightened to improve conciseness without losing critical 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?

Comprehensive coverage of prerequisites, success/failure behaviors, edge cases (captured flag, change vs. non-change), and post-requisites (confirm_capture_review, fresh version). Despite no output schema, the description thoroughly explains what happens on success and failure, making it complete for a complex 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?

Schema description coverage is only 29%, so the description compensates significantly for the core `policies` parameter by explaining the one-policy-per-title structure and complete-set requirement. It also hints at the approval mechanism for removed policies, though it does not explicitly name `removal_count` or `removal_token`. Some parameter semantics remain implicit but the main data parameter is well clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Save the Significant Accounting Policies text (Note 2) your user has chosen, one policy per title.' It identifies the specific resource (Note 2 policies) and action (save), distinguishing it from other save_* tools that handle different statement sections.

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 explicit usage directions: 'Call list_statement_policy_choices first and send back every title,' and instructs to confirm the disclosure review with confirm_capture_review after saving. It also outlines approval flow for dropped policies and warns against unrecognized headings, giving clear when-to-use and prerequisite guidance.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses the atomic nature of the entry, the immediate effect of new entries, and the two-step approval process for replacements, including the fact that nothing changes until the request is resent. It also clarifies that amounts are strings in rupees, adding significant operational detail.

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 three sentences, front-loaded with the primary function, and every sentence adds essential detail about the workflow and constraints. There is no redundant or filler content.

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?

While the description explains the high-level workflow and approval process, it omits details about how the replacement mechanism works (e.g., what 'approval details' are, how removal_count/removal_token relate) and provides no output schema. Given the tool's complexity and multiple parameters, this is a notable gap, though the core behavior is adequately 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?

The schema description coverage is only 14% (solely client_id), yet the description does not compensate for the undocumented parameters such as period_id, template_id, entry_no, lines, removal_count, and removal_token. It adds some context (rupee strings, balanced entry) but leaves the meanings and usage of most parameters unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool saves a balanced adjustment journal entry (debits = credits) as an atomic whole, distinguishing it from sibling save tools. It also distinguishes between creating a new entry (immediate) and replacing an existing one (requires approval), making the purpose highly specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides concrete procedural guidance on when to expect immediate execution vs. an approval workflow, and instructs the user to resend the request with approval details. However, it does not explicitly name alternatives or state when not to use this tool compared to sibling save_* tools, 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 indicate this is a non-read-only, non-destructive write operation (readOnlyHint=false, destructiveHint=false). The description adds the specific categories of movements being saved but does not disclose whether existing movements are overwritten or appended, nor any validation rules beyond the 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?

Single sentence with information-dense structure—front-loaded verb/resource, parenthetical enumeration of movement types, and scope qualifier. No redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has moderate complexity (nested array, 4 required params) and no output schema. The description covers the core operation but omits guidance on where template_id/period_id come from (e.g., list_periods) and what the response indicates. Overall adequate but with 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?

Only one of four top-level parameters (client_id) has a schema description; the description compensates partially by enumerating movement fields (additions, deletions, depreciation charge, depreciation on deletions), but does not explain period_id or template_id or the array structure's upsert behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Save' with clear resource 'fixed-asset movements' and enumerates the movement types (additions, deletions, depreciation charge, depreciation on deletions) plus scope 'per gross-block line for the PPE schedule', which distinguishes it from sibling save_* 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?

The phrase 'for the PPE schedule' provides clear context that this tool is for PPE-related fixed-asset movements, but there is no explicit mention of alternatives or exclusions. Among siblings like save_provision_movements and save_reserves_movements, the description implies its specific use case.

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 indicate this is a non-read-only, non-destructive write operation. The description adds a valuable behavioral guardrail: disclosure sections may contain personal names, so the agent must pass through only user-provided content verbatim. This goes beyond annotations, though it does not mention the payload's structured numeric sections.

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 two sentences with the action front-loaded. Every word contributes: the first sentence states what the tool does, and the second provides a critical safety instruction. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the extremely large and nested payload schema, no output schema, and sparse annotations, this description is insufficiently complete. It focuses only on the text-like nature of disclosures and omits the structured sections (e.g., ageing tables, paise amounts, shareholder details) that dominate the schema. The warning about names is useful but does not fill the contextual gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25% (only client_id is described). The description gives no specific parameter-level guidance for the complex payload, merely stating that the tool saves text sections and warning about exact transmission. It does not compensate for the low schema coverage, leaving the many nested payload fields unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: saving notes/disclosures text sections provided by the user, with the statement as the target context. It is specific about the verb and resource, but it does not distinguish itself from sibling save_* tools (e.g., save_adjustments) and the term 'text sections' undersells the structured payload.

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 description implies usage when the user provides disclosure sections, and it gives a strong behavioral rule to only send user-provided content exactly as given. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.

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

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

The description richly discloses behavioral traits: replacing the whole section, treating renamed partners as removal+addition, handling repeated names as separate rows, approval triggers, mid-year change limitations, ratio warning behavior, and the need to read back after saving. This goes far beyond the annotations (destructiveHint=true) and adds substantial context 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 lengthy but dense with necessary warnings and usage constraints. It front-loads the core purpose and then methodically covers behavioral rules, approval flows, and post-save actions. Every sentence contributes value; however, it could be slightly streamlined without losing critical 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?

Given the tool's complexity (8 params, destructive, approval workflow, no output schema), the description is exceptionally complete. It covers purpose, usage, parameter semantics, behavioral warnings, and post-save verification, making it fully actionable for an agent. The absence of an output schema is mitigated by instructions to read back the section.

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 schema description coverage at only 25%, the description compensates by explaining key parameters: account_kind (Note 3a/3b), share_pct (profit-sharing ratio), person_name (repeated names kept as separate rows), and the concept of a complete schedule. It doesn't explicitly define all numeric fields (e.g., opening, withdrawals), but it gives enough context. The approval-related parameters (removal_count, removal_token) are discussed implicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Save'), the resource ('partner or owner capital schedule'), and the specific context ('for an LLP or other non-corporate entity — Note 3a (capital account) or Note 3b (current account)'). This distinguishes it from siblings like get_partner_capital (read) and save_share_capital (share capital).

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 description gives explicit guidance on how to use the tool: send the complete schedule, one section per call, and approval flow for removals/changes. It also references an alternative (get_partner_capital) for reading back. However, it doesn't explicitly say when not to use this tool versus sibling save tools, though the entity type and note specification imply it.

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 annotation destructiveHint=true, the description discloses critical behavioral traits: omitted saved lines stay unchanged (upsert semantics), removals first trigger an approval request and nothing changes until the request is resent with approval details, and the two removal modes are mutually exclusive. This provides significant operational context beyond the mere 'destructive' flag.

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 five sentences long and front-loaded with the core action. Each sentence adds valuable detail: upsert behavior, omission semantics, removal modes, approval flow, and required workflow. It is slightly longer than ideal but appropriately so given the tool's complexity and destructive potential.

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 tool with destructive capabilities and an approval workflow, the description covers the essential semantics: upsert behavior, removal handling, and the resend-with-approval process. It does not explicitly state the success response for regular saves, but given the output schema is absent and the workflow is clearly outlined, this is a minor gap. Overall, it gives an agent enough context to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (13%), and the description compensates well by explaining key parameters: remove_leaf_codes, clear_all, and the movements array (additions, utilised). It also hints at approval tokens via 'approval details.' However, it does not explain template_id or period_id, nor the exact format constraints for additions, so the compensation is strong but not complete.

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 opens with a specific verb 'Upsert' and clearly identifies the resource as 'provision movements' per provision line. It also differentiates from sibling save tools (e.g., save_asset_movements) by naming the target. The additional detailing of removal modes and the upsert semantics leaves no ambiguity about what the tool does.

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 description provides clear context on when to use the tool (to save provision movements) and how to handle removals (via remove_leaf_codes or clear_all, never both). It also outlines a workflow: review current movements in the Schedule III workspace, then resend with approval details. While it does not explicitly name alternative tools for other movement types, the context is clear enough for an agent to select this tool appropriately.

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 provide false flags for readOnly, openWorld, and destructive hints, so the description carries the burden of explaining behavior. It discloses that the prior-year column auto-fills from the previous year's Trial Balance and that this tool overrides that value with audited figures. This adds valuable context beyond 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 a single, moderately long sentence that efficiently conveys purpose, usage, and a workflow hint. It is front-loaded with the main action, followed by context and conditional use. All parts are relevant, though it could be split into two sentences for readability, but it remains concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (write operation, 4 params, no output schema), the description covers the core function, the auto-fill mechanism, and when to use it. It lacks details on return values or side effects beyond 'override,' but the essential context for correct invocation is present.

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 only 25% (only client_id has a description). The description does not explain any parameters; it only vaguely references 'one or more statement lines,' which hints at the 'values' array but does not clarify leaf_code, amount, period_id, or template_id. With low schema coverage, the description fails to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Override the prior-year comparative for one or more statement lines with an audited figure.' It uses a specific verb ('override') and resource ('prior-year comparative'), and the title 'Save prior-year comparatives' reinforces this. It distinguishes from sibling tools by focusing on prior-year comparatives, unlike save_adjustments or save_disclosures.

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 description explicitly provides usage conditions: 'use this only when the audited financial statements differ from that figure... or when there is no previous-year Trial Balance to derive from.' It also instructs the agent to 'ask your user for the audited figures in those cases,' giving clear when-to-use and workflow guidance.

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

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

Beyond the destructiveHint annotation, it explains the complete replacement behavior, the approval-request flow when dropping saved affirmations, the re-opening of disclosure review, and the requirement to ask each affirmation individually. No contradictions.

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 lengthy but each sentence carries critical safety information; it is front-loaded with purpose and the complete-set imperative. Could be tightened without losing meaning, but for a destructive tool this level of detail is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, destructive nature, and no output schema, the description covers data-loss risks, approval flow, integration with list_statement_policy_choices and confirm_capture_review, regulatory representation cautions, and re-generation. It 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 coverage is only 29%, so description must compensate. It explains the affirmations object semantics (one per title, complete set, exact headings) and implicitly covers removal_count/removal_token via the approval request. It lacks explicit syntax for template_id/period_id, but those are common identifiers.

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 it saves 'CARO / Other Regulatory Information affirmations your user has confirmed' and explicitly contrasts with reading via list_statement_policy_choices, distinguishing it from sibling tools like save_disclosures. The verb 'save' + resource + scope is specific.

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 explicitly instructs to call list_statement_policy_choices first, to resend the complete set, and to confirm disclosure review with confirm_capture_review. It also specifies when the tool refuses (ICA formats with no note) and how to handle approval requests.

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 indicate destructiveHint=true, but the description adds substantial behavioral detail: 'Omitted saved lines stay unchanged,' 'An actual removal first returns an approval request; nothing changes then,' and the need to resend with approval details. This goes well beyond the binary annotation flags and clarifies the side effects of removal.

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 concise and well-structured, with five sentences each serving a distinct purpose: primary action, update behavior, removal modes, approval flow, and procedural next step. It is front-loaded with the core verb and resource, and there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main behaviors (upsert, removal modes, approval workflow) and even gives a procedural hint ('Review current movements in the Schedule III workspace, then resend...'). However, with no output schema and low schema parameter explanation, it does not specify what the tool returns or the exact form of the 'approval details' (e.g., removal_token/removal_count), leaving some ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 13%, so the description carries the burden. It explains the removal parameters (remove_leaf_codes, clear_all) and their exclusivity, and mentions the movement types (transfers in/out, dividends, other changes). However, it does not explain the core required parameters (client_id, template_id, period_id) in any detail, and the structure of 'movements' is left to the schema. It adds some meaning but does not fully compensate for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Upsert reserves/equity movements (transfers in/out, dividends, other changes) per reserves line.' This specifies the action (upsert), the resource (reserves/equity movements), and even the type of movements, distinguishing it from sibling tools like save_asset_movements and save_provision_movements.

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 description provides clear context for when to use the tool (for reserves/equity movements) and gives explicit instructions for removal modes: 'pass remove_leaf_codes; to remove the entire saved set, pass clear_all (never both).' It also explains the approval resend workflow. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations show readOnlyHint=false, so a write operation is expected, but the description adds no behavioral details like overwrite semantics, validation rules, or idempotency. It merely restates the data being saved, providing minimal insight into operational effects.

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 a single, focused sentence that front-loads the purpose and lists the key data items with no extraneous content. Every clause contributes 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 8 required parameters and no output schema, the description only explains the data inputs but leaves out crucial context: when to use, what happens on conflict, and how the identifiers relate. The agent lacks enough guidance for correct invocation in varied situations.

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 low (13%), but the description paraphrases the share-related parameters ('opening share count', 'shares issued', 'amounts'), adding some semantic context. However, it does not explain the identifier parameters (client_id, period_id, template_id) or amount formatting beyond the schema patterns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.