schedule-iii

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

Beyond the readOnlyHint=false annotation (which already marks it as a write), the description discloses significant behavioural traits: it 'clears Datavrn’s refusal to finalise', that Datavrn refuses if previous-year figures changed after reading state, and that the record can be withdrawn (restoring the refusal). It also stresses that the assertion is recorded in the named member's name and kept with the statement. This is rich, non-obvious 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 lengthy but appropriately so given the professional and irreversible nature of the action. It is front-loaded with the core purpose and conditions, then details the workflow and caveats. A few sentences could be tightened, but every sentence serves a purpose, so it is well-structured and not padded.

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 write tool with no output schema, the description covers all necessary context: prerequisites (get_comparative_source_state), the exact user interaction (read out finding, get go-ahead), failure modes (changed figures), and withdrawal (restores refusal). An agent has everything needed to call it correctly and safely.

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 each parameter already has a description, but the tool description adds essential semantic guidance: reason must be 'your user’s own words' and never paraphrased, confirm_token comes from get_comparative_source_state, and on_behalf_of has API-key vs OAuth rules. This is exactly the kind of extra meaning that helps an agent use parameters correctly 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 ('record') and a precise resource ('your user's assertion that the previous year genuinely had no activity'), along with the broader intent (making the all-nil previous-year P&L a fact, not a closing-entry artefact). It distinguishes this from the 'other two remedies' in get_comparative_source_state, so an agent can separate it from 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?

Usage is explicitly conditioned: 'Only send it when your user has told you, in their own words, that the previous year had no activity' and 'If they are unsure... do not call this'. It also spells out the required workflow: call get_comparative_source_state first, read out the finding, get explicit go-ahead, and send the confirm_token. This leaves no ambiguity about when to use 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?

Despite annotations already marking destructiveHint=true and readOnlyHint=false, the description adds deep behavioral context: confirmation is pinned to the reviewed set, later saves withdraw it, re-confirmation supersedes and marks the prior as withdrawn, it invalidates finalise approvals, notifies the named member, and requires a fresh version. This goes far beyond the annotations and is critical for safe invocation.

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. It front-loads the core purpose, then addresses exclusions, consequences, and prerequisites in a logical order. Every sentence carries meaningful guidance (e.g., the version-generation note, the notification behavior). While it could be trimmed slightly, the complexity of the tool justifies the length.

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 presence of destructive side effects, the description covers the essential context: prerequisites (show and get go-ahead), exclusions (only two sections), behavioral consequences (withdrawal, supersession, invalidation), and operational requirements (fresh version). It does not describe the return value, but no output schema is present and the description implies what the response names (withdrawn confirmations). Overall, it is sufficiently complete for an agent to use 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 only 29%, so the description should compensate, but it focuses on behavior rather than parameter details. It does explain that reason_code enumerates the two valid sections, and that capture_kind likely indicates which capture type, but it doesn't explicitly map parameters to their roles. The schema itself provides descriptions for client_id and on_behalf_of, but note is undocumented in both. The description adds context that helps infer some parameters, but not enough to 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 states a specific action ('Record your user's confirmation that they have REVIEWED a whole section') and clearly identifies the two resources ('previous-year comparative column' and 'entire disclosure set'). It distinguishes itself from saving operations, saying 'Saving figures or text does NOT complete these two sections'. This is precise and removes ambiguity against sibling tools like save_disclosures or save_py_values.

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 this, show them what you are confirming... and get their explicit go-ahead') and when-not-to-use ('Never confirm a review that has not happened'). It also explains that every other section uses saving or declare_capture_na, and explicitly warns against retries when confirmation doesn't stick. This fully routes the agent to the correct context.

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 indicate destructiveHint=true, but the description adds useful non-obvious behaviors: it runs validation and returns the full result (row counts, warnings, blocking issues), never auto-applies mapping suggestions, and requires user-approved mappings. It also instructs reviewing warnings before ingesting. This goes beyond what annotations alone convey, though it doesn't explicitly describe side effects or what is destroyed.

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, each earning its place: the first defines the action, the second states the return value, and the third provides a critical caveat. It is front-loaded with the main purpose and wastes no words.

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 has a nested `options` object and no output schema, the description does well to state the return value (full validation result with row counts, warnings, blocking issues). It also places the tool in the workflow ('staged upload', 'before ingesting'). However, it omits any explanation of the optional `options` parameters and `save_as`, which would be needed for full understanding of all inputs.

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 25% (only upload_id has a description). The description partially compensates by explaining that 'mapping' must be the exact mapping the user approved, and it references the upload_id as coming from a staged upload. However, the nested 'options' object and 'save_as' parameter remain completely unexplained, leaving a significant gap for a tool with four parameters.

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: 'Confirm the column→field mapping for a staged upload and run validation.' It names the exact resource (column→field mapping) and the verb (confirm/run validation), distinguishing it from sibling confirm_* tools that target other mappings (e.g., centre_mappings, groupings, reporting_lines).

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 contextual workflow guidance: 'for a staged upload' and 'before ingesting.' It also provides a key directive: 'Mapping suggestions are never auto-applied — pass exactly the mapping your user approved' and advises reviewing warnings before ingestion. While it doesn't explicitly compare to alternative tools, it clearly implies this is the step after upload_trial_balance and before ingest_upload.

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/destructiveHint annotations, the description explains that this action marks the upload as evidence, affects future wrong-entity detection, refuses and changes nothing under certain conditions, and does not alter landed figures. This is substantial behavioral context not available from annotations alone.

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 well-structured: purpose first, then required workflow, warnings, and refusal conditions. Every sentence contributes to safe use, though it is more verbose than strictly necessary for a five-parameter 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?

Prerequisites, side effects, refusal conditions, and authorization are all covered. The main gap is that it does not describe what a successful response contains, especially since there is no output schema. This is minor for a confirmation action but still a slight omission.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds critical invariants: state_digest and confirm_token must come unchanged from the same preview_chart_rebaseline response, source_snapshot_id comes from list_chart_rebaselines, and on_behalf_of is required on API-key connections but omitted on OAuth. This meaningfully exceeds 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 states a specific verb and resource: recording explicit confirmation that an upload is an entity's complete current chart of accounts. It clearly differentiates this from sibling confirm_* tools by tying it to preview_chart_rebaseline and emphasizing it is a professional judgment, not a calculation.

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 the agent to call preview_chart_rebaseline first, read counts, ask the user plainly, and send back the state_digest and confirm_token from the same response unchanged. It also lists conditions under which Datavrn refuses and notes when answering a direct Datavrn question is the alternative.

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

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

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?

With all annotations false, the description carries the full burden and delivers: it never copies review confirmations, skips sections with existing answers, and warns about the version/finalisation dependency ('finalisation checks the version’s frozen capture state'). These are non-obvious behaviors not otherwise visible.

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 contributing distinct information: the core action, exclusions, user approval requirement, and versioning caveat. No filler or redundancy, and the key action is 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?

The description covers the tool's purpose, exclusions, prerequisites, existing-answer preservation, and finalisation impact. No output schema exists, so return-value documentation is not needed. It is sufficiently complete for a tool with this 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 50% (client_id and on_behalf_of have descriptions). The description indirectly clarifies period_id by distinguishing 'previous period' from 'this period', but does not explain template_id or map the parameters explicitly. It adds some semantic value but leaves gaps.

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 the exact action: 'Copy the previous period’s "nothing this period" and "does not apply" answers into this period, for sections that have no answer yet.' It also distinguishes itself from sibling tools by explicitly noting it never copies a review confirmation, which separates it from confirm_capture_review.

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 clear usage context: 'get their go-ahead before calling it' sets a prerequisite, and 'Answers already recorded for this period are left alone' defines scope. It also excludes review confirmations, giving clear when-not-to-use guidance, even though it does not name alternative 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 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the full transparency burden. It discloses the link's 15-minute expiry, single-entity staging, and that nothing is ingested until column mapping is confirmed. It also explains the separate URLs and the hash-comparison step for the POST reply, giving the agent a complete behavioral model.

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

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

The description is dense with critical operating details, front-loaded with the core purpose and then the two delivery paths. While longer than average, every sentence serves a purpose—no filler. It could be tightened slightly, but the complexity of the workflow justifies the length.

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 (mutating, two delivery URLs, expiration, hash verification), the description covers the main usage correct. A minor gap: it doesn't explicitly state the tool's response contains upload_url and upload_post_url, though it alludes to them. Lacking an output schema, a direct mention of the returned fields would make it fully complete, but the description still enables correct usage.

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 adds meaning: it explains that 'format' should be left unset (only trial balance accepted), 'source' is set to 'tally_file' for Tally exports, and elaborates on the purpose of 'file_name' and 'client_id' (from list_clients). This goes beyond mere schema text with concrete usage 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 the tool mints a single-use, login-free upload link to get a file to Datavrn, and explicitly contrasts it with inlined base64 in context. It specifies the verb (mint), resource (upload link), and distinguishes itself from sibling upload tools like upload_trial_balance by focusing on the link mechanism rather than direct upload.

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 instructions: use when a human has the file, or when the agent holds a file larger than ~10 KB. It also details the two delivery methods (human opens upload_url, or programmatic POST to upload_post_url) and warns against using context for large files. It even covers edge cases like refusing non-trial-balance formats, directing to the web app instead.

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, but the description goes well beyond: it explains superseding behavior (old answer marked withdrawn), refusal when a current answer stands, the need to revoke first, invalidation of finalise approvals, and the requirement to generate a fresh version. This adds rich contextual detail about side effects not captured in annotations, and there is no contradiction with 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 long but every sentence conveys essential information. It is front-loaded with the core purpose, then moves to restrictions, then to mutational behavior. Each paragraph handles a distinct topic without redundancy. It is dense and well-structured, though slightly lengthy; for a tool with this many nuances, the length is justified and earn-worthy.

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 has no output schema and low schema coverage, the description covers all critical operational aspects: the three declaration types, allowed reason codes per section, the supersede/withdraw/revoke lifecycle, invalidation of approvals, and version generation. It also mentions what the response names (the withdrawn answer). Nothing an agent needs to safely invoke this mutation tool is missing.

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

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

Schema description coverage is only 29%, so the description must compensate. It does for the most critical parameters: reason_code semantics are fully explained (three meanings and their non-interchangeability), and capture_kind restrictions are detailed (settings no answer, share capital/partner capital only 'nothing this period', 'first year' only for previous-year figures). However, it does not clarify the 'note' parameter or explain period_id/template_id beyond their obvious names. Since the core decision logic is covered, this is a strong but not perfect compensation.

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

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

The description states a specific verb and resource: 'Record that a capture section had NOTHING to report this period, DOES NOT APPLY to this entity, or that this is the entity’s FIRST YEAR'. It clearly distinguishes the three distinct statements and explicitly differentiates from the sibling confirm_capture_review by stating that tool makes a different assertion. The purpose is unambiguous and separate from other 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 gives explicit when-to-use guidance: it tells the agent to call get_schedule3_workspace and read allowed_reason_codes before asking the user, so invalid choices are never offered. It also names an alternative (confirm_capture_review) for review completion, and provides per-section restrictions (settings takes no answer, share capital/partner capital only 'nothing this period'). This is thorough, actionable 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 destructiveHint annotation, the description discloses critical behaviors: 'THERE IS NO UNDO', the operation is not approval or adoption, and 'Datavrn will refuse if anything about the statement changed after you read the state.' It also explains the 'reused' response scenario and the paused/retry behavior, adding substantial context beyond the structured 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?

Though lengthy, the description is front-loaded with the core purpose and every sentence carries critical operational or safety information. It avoids redundancy by structuring warnings and prerequisites logically, and the complexity of the tool justifies the length.

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, lack of output schema, and low schema description coverage, the description is exceptionally complete. It covers prerequisites, exact workflow, error handling (reused, refused), and post-finalisation verification via get_job, leaving no major contextual gaps for an agent 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?

The description adds important meaning for confirm_token and acknowledgments (e.g., 'send the confirm_token it gave you', 'Never write the acceptance reason yourself'), addressing low schema coverage (40%). However, it does not explicitly explain snapshot_id or client_id beyond what the schema states, leaving some inference required for the version-to-snapshot relationship.

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 precisely what the tool does: 'Seal a statement version as Datavrn's permanent client copy, recorded as authorised by the member you name.' It clearly distinguishes from sibling tools like confirm_* or save_* by introducing the unique concept of a permanent, sealed copy and explicitly referencing finalise-specific prerequisites (e.g., 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 provides explicit when-to-use guidance: 'Call get_finalise_readiness first, show your user every gate and every warning...', and warns against re-calling: 'Do not call finalise_statement again.' It also directs follow-up via get_job, contrasting with alternative actions and clarifying the irreversible context.

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 only provide readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden. It fully discloses side effects: the approval is single-use, expires in 15 minutes, tied to statement/connection/member, and can be refused if figures change. It also explains that this tool can return a post_closing_detected flag and instructs the agent to report the full finding to the user, which is a behavioral mandate.

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 ~140 words, long but densely packed with necessary safety-critical information. It front-loads the core purpose, then explains the problem, remedies, and constraints in a coherent flow. No redundancy, but it is long; however, given the complexity and the need to instruct the agent on handling the finding, it is justified. Slightly exceeds ideal conciseness but earns its length.

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 the output indirectly (post_closing_detected flag, approval object) and the exact actions the agent must take. It covers the main scenarios (post-closing detected, nothing wrong) and all constraints (expiry, ties, refusal). No output schema exists, so the description must compensate, and it does so well, though it doesn't enumerate the full return structure (e.g., whether it returns the three remedies explicitly). Minor gap, but sufficient for correct usage.

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 detailed descriptions for each parameter (uuid formats, template examples, on_behalf_of email rules). The tool description does not add meaning beyond the schema; it focuses on behavior and workflow rather than parameter specifics. Baseline 3 is appropriate as the schema already covers 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?

Purpose is crystal clear: 'Check whether this statement’s previous-year comparative can be sealed, and get the approval assert_previous_year_no_activity needs.' It names the specific verb, resource, and ties to the sibling tool. The context about the all-zeroes P&L problem distinguishes it from other tools like save_py_values or upload_trial_balance.

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 tells the agent when to use it (when previous-year figures come from a post-closing trial balance) and what to do: read the whole finding, let the user choose among three remedies, never choose for them. It also states when no approval is needed. This is exemplary usage guidance, going beyond just 'when to use' to provide a decision tree.

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 a wealth of behavioral nuances beyond what annotations indicate (readOnlyHint=true, openWorldHint=false): page_token fingerprinting, stale-run disclosure, caveats like owned_share_capital_caveat and domestic_cash_flow_caveat, conditions for withheld cash flow, and row_role semantics. It goes far beyond the safety profile and explains exactly how data is presented and qualified.

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 deliberately structured with clear section headers (CONSOLIDATED data class, QUALIFICATIONS, WITHHELD CASH FLOW, ROW ROLES). The core purpose is front-loaded in the first sentence, and each subsequent section adds essential operational details rather than filler. Every sentence contributes to correct invocation and interpretation, justifying the length for a tool of this 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 carries the full burden of explaining the return format and constraints. It covers presentation currency, decimal-string amounts, row roles and summation rules, caveats and their handling, withheld cash flow semantics, and the unavailable status. It also addresses edge cases like foreign members and missing opening basis, making it remarkably complete for an agent to call and interpret 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?

While the schema covers 100% of parameters, the description adds meaningful semantics: page_token is described as 'signed continuation from the prior page; restart without it if source_changed', periodicity is elaborated with exact grammar (monthly YYYY-MM, quarterly FYyyyy-Qn, annual FYyyyy), and the statement enum's meaning is implied through the consolidated context. This elevates understanding beyond the raw 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 opening sentence clearly states the verb ('Read'), the resource ('sealed group profit-and-loss, balance-sheet, or cash-flow face'), and the scope ('for an exact periodicity and period'). It distinguishes this tool from siblings like get_statement_figures or get_tb_rows by emphasizing 'sealed' and 'consolidated', leaving no ambiguity about which surface it targets.

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: reading consolidated statements for a sealed run. It also explicitly states exclusions, e.g., 'Consolidated cash-flow is available only for an all-domestic group in v1' and explains when cash flow is withheld. While it doesn't name alternative tools, it gives strong directional guidance on use cases and constraints.

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 reveals important behavioral traits beyond the annotations: it re-reads the stored workbook (explaining why polling is discouraged), the approval is 'single-use, expires in 15 minutes, and is tied to this exact version, this connection and the member you name,' and it clarifies that non-permitted connections still get the full state but no approval. This adds significant context that the annotations do not convey.

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

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

The description is long but each section serves a purpose: usage timing, user display requirements, side-effect caveats, and permission behavior. It is front-loaded with the core purpose and the key warning. The length is justified by the tool's complexity, though it could be tightened slightly.

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

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

There is no output schema, so the description must explain what the tool returns. It details every row type (gates, warnings, empty input cells, unevaluated controls, capture_live_diverged_message) and explains their meanings. It also covers the full lifecycle from call to finalise and the failure mode if the state changes, making it complete for this 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?

The schema provides descriptions for all three parameters (100% coverage), including format hints and which are required. The description does not add specific parameter-level semantics beyond referencing 'the member you name' and 'your user', so the 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 a specific verb+resource: 'Read the full finalisation state of one statement version, and get the approval finalise_statement needs.' This clearly states what the tool does and differentiates it from the sibling finalise_statement by positioning it as the prerequisite readiness check. The title also reinforces the 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 explicit timing: 'Call it ONCE immediately before finalising — it re-reads the stored workbook, so do not poll it.' This provides a clear when-to-use instruction and an exclusion (do not poll). It also explains the consequence of stale state ('finalise_statement will refuse'), which guides the agent on when to re-run 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?

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=true and destructiveHint=false, but the description adds substantial behavioral context: the login requirement for deep links, the default-period logic ('not necessarily the newest'), the 30-day undo window and the fact that no message announces its expiry, and the ordering of restorable_replacements. This goes well beyond what annotations provide and helps the agent understand side effects and risks.

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, covering two distinct purposes and relevant nuances without fluff. It front-loads the primary purpose and the parameter behavior early, then introduces the secondary replacement feature. The structure is logical, though a bit sprawling; it could be split into bullets for readability, but it remains coherent.

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 there is no output schema, the description fully explains the return structure (per-entity row details, restorable_replacements with their fields, counted omissions) and provides necessary context about the login requirement and the undo-window risk. It also directs the agent to relevant sibling tools for follow-up actions, making it complete for correct invocation.

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

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

Only one parameter, period_label, with 100% schema description coverage. The description enriches it by explaining the default behavior in more depth than the schema (e.g., that a future-period upload won't flip the board) and how to intentionally pass a label. This adds value over the schema's description, so it earns above the 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 states a specific question it answers ('what's left to do?') and details exactly what it returns for each entity (trial balance status, ungrouped accounts, latest version, finalised flag) plus the second distinct purpose of listing restorable replacements. This is highly specific and clearly distinguishes it from siblings, as it explicitly claims that the replacement functionality is unique ('nothing else here 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 explains when to use the tool (to answer pending-work or replacement questions), gives parameter guidance (how to select a period or rely on the default), and suggests follow-up tools (list_replacements, preview_replacement_restore) for acting on the returned IDs. It does not explicitly state when not to use it or contrast with a sibling, but the 'nothing else here does' phrase implies a unique role.

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 annotation, the description discloses extensive behaviors: null verdicts mean UNKNOWN not pass, old versions return available:false with a specific reason, it never recomputes from live books, figures match the workbook, amounts are decimal strings, and the EPS rows are per share and excluded from totals. This far exceeds 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 long but densely packed with necessary information, organized into clear sentences and paragraphs. It front-loads the primary purpose and then covers edge cases and exceptions. While longer than average, every sentence earns its place—for instance, the EPS rule and null-verdict semantics are critical for correct usage. Not excessively verbose.

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 4 parameters, no output schema, and no enums, the description fully equips an agent: it details all return categories, handles versioning edge cases, explains the EPS exception, and provides recovery instructions for unavailable figures. The inclusion of 'frozen control changes' and 'never recomputes' clarifies non-obvious behavior. Nothing essential is missing.

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

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

Schema description coverage is 100% as all 4 parameters have descriptions. The tool description adds no additional parameter-level detail beyond what the schema already states (e.g., version meaning latest unless specified is already in the schema). Baseline 3 applies because the schema does the heavy lifting; no compensation 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 precisely states the tool reads a generated Schedule III statement's figures, enumerating the exact elements (balance-sheet and P&L faces, tie verdicts, unclassified count, notes, exception counts, control changes). It distinguishes itself from sibling get_statement_notes by explicitly routing line-by-line breakdowns to that tool. The verb 'read' and resource 'statement figures' are 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?

Clearly states when to use this tool versus the alternative: 'For a note's line-by-line breakdown, use its note_index entry with get_statement_notes.' It also provides recovery guidance for old versions (regenerate, read latest, retry) and clarifies that interpretation is the assistant's responsibility. No exclusions are missing.

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 declare destructiveHint=true, and the description goes further by describing the exact destructive scenario (permanently deleting trial-balance rows), the refusal-on-first-call behavior, and the short-lived token as the only acknowledgment. It also discloses that two parameters are ignored on this connection, which is critical for correct invocation. 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 every sentence carries essential operational detail: purpose, conditional flow, token handling, ignored params, and return value. It is front-loaded with the core purpose. Slight verbosity, but justified given the two-call complexity; 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 destructive tool with no output schema and 6 parameters, the description covers the approval flow, the token lifecycle, the ignored fields, and the return value (ingestion outcome with notices). It assumes a prior 'validated upload' step, which is reasonable given sibling upload_trial_balance. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 67%, so the description is expected to fill gaps. It explicitly explains removal_token and removal_count (exact counts, token short-lived, resend unchanged) and states acknowledged_state_digest is ignored. However, confirm_merges is not mentioned at all, and acknowledge_warnings only gets a dismissal. Still, the description adds substantial meaning for the most security-sensitive parameters, going 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 opens with a specific verb and resource: 'Commit a validated upload into the entity’s books.' It clearly differentiates this from upload_trial_balance (which creates the upload) and other confirm_* siblings by framing it as the final commit step. The two-call approval mechanism is prominent, making the tool's unique role 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 a token is required (warnings or destructive over-write) vs when a simple additive ingest suffices. It instructs the agent to show warnings and counts, get explicit go-ahead, and resend with the token. It also clarifies that acknowledge_warnings is ignored, preventing misuse. This is as explicit as usage guidance gets.

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?

The description claims 'This call only lists' and 'NOTHING WAS REJECTED, BLOCKED OR CHANGED', implying a read-only operation. However, the annotation readOnlyHint is false, which suggests the operation may not be read-only. This directly contradicts the description, so per the rules the score is 1.

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

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

The description is front-loaded with the core purpose, then explains the semantic distinctions of shortfall and the three cases. While lengthy, most sentences serve a clear purpose for an accountant-facing tool, though it could be trimmed without losing essential information.

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

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

With no output schema, the description thoroughly explains the returned row fields (trusted_considered, incoming_considered, matched, coverage ratios, shortfall, reason), the null case, and guidance on how to proceed. It does not cover pagination or error conditions, but for a list-only tool this is reasonably 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 100%, and both parameters are well described in the input schema. The tool description adds no additional parameter semantics beyond what the schema already provides, so the 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 states a specific action ('List the uploads Datavrn is NOT counting as evidence'), names the exact resource ('uploads not yet counted as identity evidence'), and differentiates from the sibling preview_chart_rebaseline and confirm_complete_chart. It is unmistakable 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 explicitly says when to use it ('This call only lists') and when to use the alternative ('To confirm one of these uploads, call preview_chart_rebaseline'), and also explains the normal state of an empty list. This gives clear routing guidance with no ambiguity.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: 30-day retention window, state transitions (restorable/lapsed/restored), the unattended-only filter, the connection attribution caveat, and the semantics of window_closes_at. This goes far beyond the annotations and is essential for correct use.

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 information. It front-loads the core purpose, then states lifecycle, exceptions, and alternatives. For the complexity (state machines, undo windows, attribution caveats), the length is justified. Slight structure improvements could split into paragraphs, but it's coherent and efficient.

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 no output schema, the description explains the return contents (what was overwritten, record counts, undoability) and all state values. It covers the full workflow: when to call, what to expect, and what to do afterwards (preview/restore or support). Nothing an agent needs is missing.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds provenance guidance: client_id comes from list_clients, connection_id from get_pending_work or the web app. This is valuable, though not exhaustive—it doesn't explain format or edge cases. Still, it elevates beyond the schema 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 states a specific verb ('list') and resource ('what a connected data source’s AUTOMATIC syncs have REPLACED for one entity') and enumerates what each entry shows. It clearly differentiates from siblings like get_pending_work by naming it as the alternative for cross-entity discovery, and preview_replacement_restore/restore_replacement as follow-up actions.

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 call: 'when a user says figures for a past period look wrong or changed on their own, and after any surprise in a period a connector covers.' It also gives a direct when-not: manual confirmations are excluded by design, and provides an alternative (get_pending_work) for the case without a connection id. No ambiguity.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical side effects: the approval is single-use, expires in 15 minutes, is tied to entity/upload/member/figures, and is spent if uploads change between the call and the confirmation. It also details refusal conditions that leave state unchanged, which is essential for an agent to predict the tool's impact.

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 contributes: purpose, usage, return values, side-effect disclosure, and refusal conditions are all necessary for correct invocation. It is front-loaded with the core purpose and then expands logically. Could be tightened slightly, but 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?

With no output schema, the description fully specifies the returned data (the five counts and two ratios) and how it relates to the list_chart_rebaselines output ('re-read at this moment'). It also covers the approval's constraints and refusal conditions, so an agent has everything needed to call it correctly and understand its effects.

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

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

Schema description coverage is 100%, so the schema already documents client_id, source_snapshot_id, and on_behalf_of. The description adds only light context (e.g., 'the one upload your user is considering' and the approval's tie to the member named), but does not clarify parameter syntax or edge cases beyond the schema. Baseline of 3 is appropriate since the schema carries the detail.

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 (show) and resource (ONE upload’s figures), and explicitly ties it to the approval that confirm_complete_chart needs, distinguishing it from siblings like list_chart_rebaselines and confirm_complete_chart. It names the specific precondition (after list_chart_rebaselines) and the entity of interest, leaving no ambiguity about 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?

Provides explicit when-to-use ('Call this after list_chart_rebaselines, for the one upload your user is considering') and when-not-to-use (refusal conditions: not awaiting confirmation, already confirmed, or a directly asked upload). It also instructs the agent to never decide based on numbers alone and to ask the user, giving clear behavioural guidance for selection.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false) so the description carries the behavioral burden. It fully discloses that the tool is a preview that computes counts 'at this moment,' returns blocked_reason for locked periods, issues a single-use approval expiring in 15 minutes tied to specific parameters, and warns that undoing a sync is itself destructive. This exceeds what annotations convey and adds critical context about side effects and failure modes. 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 approximately 250 words—long but not bloated for a safety-critical approval tool. However, it's a single paragraph without visual structure, and some phrases are repetitive (e.g., 'undoing a sync' appears twice). It is front-loaded with the main purpose, but could be tightened with bullet points or shorter sentences for easier scanning. Compared to the calibration examples, this is acceptable for complexity but not as crisp as ideal.

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 no output schema, so the description must explain return values; it does: destroy_count, restore_count, and blocked_reason. It also covers timing (counted at this moment), approval mechanics (single-use, expiry, binding), and failure handling (blocked_reason non-null). All necessary steps for correct invocation and follow-up are present. Given its role in an approval chain, the description is complete and self-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 descriptions cover 100% of parameters, so baseline is 3. The tool description adds contextual meaning by linking parameters to the approval context: 'this entity, this sync, this connection, the member you name' maps to client_id, event_id, connection_id, and on_behalf_of. It also explains how to feed the output (destroy_count) into the expected_destroy_count parameter of the next tool. This goes beyond schema descriptions and clarifies the operational flow.

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: 'Show EXACTLY what undoing one automatic sync would do' and 'get the approval restore_replacement needs.' It uses a specific verb (preview) plus resource (undoing a sync) and explicitly differentiates from the sibling restore_replacement by framing this as the prerequisite step. An agent can immediately understand what this tool does and how it fits the workflow.

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 usage guidance: instructs the agent to read both destroy_count and restore_count to the user, get explicit go-ahead before calling restore_replacement, and handle blocked_reason by aborting. It also names the sibling tool restore_replacement as the follow-up and warns when not to proceed. This is direct, actionable guidance with clear conditions and 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?

Beyond the destructiveHint=true annotation, the description discloses concrete behavioral implications: it destroys all data held in the period (including uploads/syncs after the replacement), is not recoverable on this surface, and notes that recovering is a support operation. It also clarifies that the tool reports a residual number for failed link re-establishment, adding depth beyond the 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 verbose (approximately 150 words) but every sentence adds critical information for a high-stakes destructive operation. It is front-loaded with the destructive warning and includes structured sections for workflow, failure conditions, and post-action reporting. While not terse, the length is justified by the operational risk and complexity, so it earns a 4 rather than 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?

Given that there is no output schema and no annotations beyond the destructive flag, the description fully compensates: it explains what the tool does, the prerequisite workflow, all rejection conditions, what success reports (destroy count, restored count, residual link count), and that the residual number must be conveyed to the user. Nothing an agent needs to call this correctly is missing.

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

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

The input schema has 100% description coverage, with each parameter already thoroughly documented (e.g., on_behalf_of's API-key vs OAuth behavior, expected_destroy_count's exactness requirement). The description does not add new parametric information beyond what the schema already provides; it only reinforces the workflow. Baseline 3 is appropriate since the schema carries the semantic 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 states a specific verb ('Undo'), a clear resource ('one automatic sync'), and precisely describes the action: destroy current data for the period and restore the replaced records. It distinguishes itself from sibling preview_replacement_restore by naming it as the prerequisite preview step, leaving no ambiguity about what this 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 explicitly instructs the agent on the exact workflow: call preview_replacement_restore first, read both numbers to the user, obtain explicit go-ahead, and pass back the confirm_token and destroy_count. It also lists multiple refusal conditions (data moved, locked period, already undone, 30-day window closed, human-confirmed replacement) providing clear when-not-to-use guidance and reinforcing the safe invocation pattern.

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 goes far beyond the annotations (readOnlyHint: false, destructiveHint: true). It reveals that "Nothing is deleted," clarifies the effect on existing versions, explains the creation of a new entry rather than overwriting, and discloses the side effect of invalidating approvals from get_finalise_readiness. This is rich behavioral context that an agent needs to predict side effects accurately.

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

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

The description is front-loaded with the core purpose in the first sentence, then branches into consequences and edge cases. While it is verbose, each sentence adds distinct information (e.g., version impact, audit trail, approval invalidation). It is structured as a coherent narrative, though some sentences could be tightened. Overall, it is appropriately detailed for the 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 the side effects and consequences of the withdrawal, which is essential for a destructive operation. However, it does not explain how the agent should specify which answer to withdraw (beyond implicitly via capture_kind and IDs), nor does it describe any return value or response format (no output schema exists). The request semantics are under-specified for a mutation tool, leaving gaps in what the agent needs to call it correctly.

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

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

The input schema has only 40% coverage, with descriptions for client_id and on_behalf_of, but none for period_id, template_id, or capture_kind. The description does not explain how these parameters map to the answer being withdrawn, nor does it clarify which specific answer is targeted. The description focuses entirely on consequences and ignores the request parameters entirely, failing to 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 description opens with a specific verb–resource pair: "Withdraw a recorded capture answer or review confirmation." It distinguishes this from recording tools like confirm_capture_review and declare_capture_na by focusing on the act of withdrawal, and the title reinforces the purpose. The purpose is unambiguous and distinct from 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 on what happens after using the tool, such as readiness status changes and approval invalidation. It also suggests an alternative action: "answer the section again and generate a fresh version." However, it does not explicitly state when to use this tool versus alternatives like confirm_capture_review, nor does it give exclusions. The guidance is implied but not fully explicit.

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

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

Beyond the destructiveHint annotation, the description discloses that the call replaces all of Note 2, that omitted titles are removed, that dropping policies triggers an approval request, that unrecognized headings are refused, and that saving re-opens the disclosure review. This fully informs the agent 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 long but every sentence adds critical operational detail. However, it is a single dense paragraph; breaking it into bullets or numbered steps would improve scannability without loss of 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?

For a complex, destructive write tool with no output schema, the description covers prerequisites, destructive consequences, approval mechanics, policy change disclosure, authorisation record, and follow-up confirmation steps. It is fully complete for an agent 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?

The schema only describes client_id and on_behalf_of (29% coverage). The description compensates by explaining that policies should be a complete map of titles, warns about exact headings, and refers to the removal_count/removal_token flow via the approval request. It doesn't explicitly name each parameter, but it gives the semantic context needed to populate them correctly.

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 that the tool saves the Significant Accounting Policies text (Note 2), one policy per title, making the verb and resource explicit. This distinguishes it from sibling save_* tools like save_disclosures or save_adjustments by naming the exact statement note.

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 step-by-step guidance: call list_statement_policy_choices first, send the complete set every time, follow up with confirm_capture_review, and generate a fresh version after last capture change. It also explains when a difference from last year is not a change, preventing misuse.

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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds context about the content being saved (movements per gross-block line) but does not disclose any additional behavior such as whether existing data is overwritten, validation rules, or prerequisites like an open period. It does not contradict 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.