AgenticBooks

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

Beyond the annotations (readOnlyHint=false, no idempotency/destructive hints), the description discloses important behaviors: auto-assignment of the next free code with no reuse of retired codes, immediate usability, conditional QuickBooks provisioning with an active/pending status, and actor_id defaulting. This adds substantial operational context not visible in structured data.

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 every sentence earns its place. It leads with the core action, then explains the auto-assignment behavior, QuickBooks integration, immediate usability, and optional actor_id. 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 creation tool with 5 parameters and an output schema, the description covers the essential decision factors: how codes are chosen, how provisioning behaves, what defaults apply, and whether the account is usable immediately. Combined with the rich schema and output schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the type-to-code-range mapping (income 4xxx, cogs 5xxx, etc.) and the automatic rollup behavior. It also reinforces actor_id/org_id defaults, though the schema already covers these.

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: 'Adds a new account to the org chart.' It clearly explains what the tool does and distinguishes it from sibling tools like rename_chart_account, set_chart_account_active, and list_chart_accounts by focusing on creation and automatic code assignment.

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 this tool applies: creating a new account, with details about type-based code ranges, P&L rollup, and QuickBooks provisioning. It does not explicitly name alternatives or state when to avoid using it, but the purpose is sufficiently distinct from siblings that usage is well implied.

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

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

Annotations only give hints (readOnlyHint=false, destructiveHint=false), but the description goes further: it explicitly states 'This WRITES financial data' and describes the atomic sequence of operations (mark reviewed, write journal lines, audit trail, queue sync). It also discloses that reason is stored verbatim and that actor_id must belong to the org. This adds behavioral context beyond annotations, with no 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 dense but every sentence carries essential information: the main action, the atomic effects, the warning about financial writes, the failure conditions, and the parameter defaults. It is front-loaded with the action and consequences, and there is no fluff. Despite its length, it is highly 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?

The tool has an output schema (not shown in the prompt), so the description does not need to explain return values. It covers prerequisites, atomicity, audit trail, ledger sync, failure scenarios, defaults, and constraints on actor_id. It also references the sibling get_unreviewed_events for context. Everything an agent needs to call it correctly 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%, so the schema already documents each parameter thoroughly (including defaults and allowed account codes). The description adds some usage context (e.g., 'only call with an account you are confident in' and the default for org_id), but it mostly reinforces the schema's content rather than adding new semantics. Baseline 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 states a specific verb ('approve'), a precise resource (one event from the review queue), and the action's effects (assigns account, writes journal lines, audit trail, queues ledger sync). It clearly distinguishes this from siblings like get_unreviewed_events and list_chart_accounts by focusing on the approval action and its side effects.

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 tells the agent when to call it (only with a confident account) and mentions the prerequisite of pulling items from get_unreviewed_events. It also states failure conditions (event not existing, wrong org, already approved) that guide when not to use it. It even warns that it writes financial data, implying caution. This is clear usage guidance beyond mere purpose.

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

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

The description adds meaningful behavior beyond the annotations: it states that the call 'links evidence only' and 'NEVER creates or changes a booking', and that already-matched documents are refused so attachments are never silently re-pointed. This complements the idempotent and non-destructive hints 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?

Four sentences with no filler. The action and scope are front-loaded, and every sentence adds a constraint, source reference, or safety clarification needed for correct invocation.

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 an output schema present and annotations covering idempotence and destructiveness, the description covers all call-relevant context: purpose, source of event IDs, refusal behavior, org-scoped defaults, and the guarantee that no booking mutation occurs. 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 coverage is 100%, so the baseline is 3. The description adds extra value by explaining that event_id is a classified event id, e.g. from list_documents proposal.candidate_ids or get_unreviewed_events, and by clarifying that actor_id defaults to the organisation entity. This goes beyond the schema 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 opens with a specific verb and resource: 'Attaches a stored document ... to a bank transaction as its evidence'. It also names the two triggering scenarios (confirming a match_ambiguous proposal or resolving awaiting_transaction/extraction_failed documents), which clearly differentiates it from siblings like list_documents or approve_classification.

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

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

Usage conditions are explicit: it should be used to confirm a match_ambiguous proposal with one of its candidate_ids or to manually resolve an awaiting_transaction/extraction_failed document. It also gives a clear when-not-to-use signal: already-matched documents are refused and it never creates or changes a booking, and it names source tools for event_id.

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 by disclosing that the operation WRITES financial data, is irreversible with no reopen flow, self-reverses entries next period, refuses double closes, and writes nothing when the soft check trips. It even notes provider-outage fail-open behavior. No contradiction with readOnlyHint=false, idempotentHint=true, or destructiveHint=false is present.

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 earns its place for a tool this nuanced. It is front-loaded with the core operation, then structured with labeled sections (IDEMPOTENT, VALIDATED, SOFT CHECK) that make complex behavior scannable. The parenthetical 'same as the web close' is minor and does not undermine the overall density of useful information.

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

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

Given the tool's high complexity, the description is remarkably complete: it covers validation rules, idempotency, soft-check behavior, no-op scenarios, per-account exclusions, self-reversals, and return contents. The presence of an output schema further reduces the need to explain return structure, and the description still does so.

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, and the schema already documents all four parameters in detail. The description adds extra semantic value by reinforcing the period_end month-end constraint and explaining the force parameter's role in the soft-check bypass, though it does not add new meaning for org_id or actor_id.

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

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

The description opens with a specific verb and resource: 'Runs the month-end (period-end) close for an organisation.' It then explains the exact mechanism (remeasuring foreign-currency balances and booking to 6750 Unrealized FX Gain/Loss) and distinguishes this from realized FX, making it clear how this differs from related financial 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 and when-not-to-use guidance: only completed months can close; future/current months are refused; already-closed periods are refused. It also explains the soft-check flow, including how to respond (surface warnings, re-call with force: true) and the no-op case for orgs without foreign balances.

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 state readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes far beyond this: it details the exact ledger effects, fee handling, cross-currency FX residual booking, the OOB approval flow, the deprecation of accept_large_fx_residual for agents, and the org-verification guards. This is rich behavioral disclosure 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 tightly packed with essential operational details, structured into clear thematic blocks (REFUSED pairs, GUARDS). Every sentence carries behavioral significance given the tool's complexity. It is front-loaded with the core action and then layers edge cases, so an agent can quickly grasp the primary use before diving into exceptions.

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 4 parameters, an output schema, and minimal annotations, the description covers all necessary invocation aspects: success behavior, fee handling, cross-currency logic, refusal paths, OOB approval, guardrails, and parameter defaults. The existence of an output schema covers return-value details, so nothing an agent needs to call the tool correctly is missing.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description adds meaningful nuance for accept_large_fx_residual by explaining it is deprecated and no longer bypasses the bound, and it reinforces the defaults for org_id and actor_id. While not exhaustive per-parameter, it enriches the schema without redundancy.

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 precise verb-resource pair: 'Books a suggested match as ONE inter-bank transfer', and elaborates with concrete mechanics (debits destination, credits source, fee line, queue removal). It clearly distinguishes the confirm action from siblings like reject_transfer by describing the booking behavior, not just restating the name.

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 strong contextual guidance on when to use the tool (confirm a suggested match) and when not to ('REFUSED pairs... do not retry a refused confirm'), and it points to the status tool for pending approvals. However, it does not explicitly name the alternative reject_transfer for refused cases, leaving some routing inference to the agent.

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 readOnlyHint, the description discloses validation against Meow's accounts endpoint, the storage-only-if open-deposit-account-exists condition, that invalid keys store nothing and return an error, the read-only scope, and key secrecy. It also explicitly states the operation cannot move money, which is important 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?

Four dense, purposeful sentences with no filler. The main purpose is front-loaded, and each sentence adds a distinct fact: auth model, validation/storage, access scope, and security handling.

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

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

Given the schema covers org_id and actor_id defaults/constraints and an output schema exists, the description covers the remaining operational essentials: prerequisites, validation behavior, failure mode, security, and access limitations. An agent has everything needed to call it correctly.

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

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

The schema already documents all three parameters thoroughly, so the baseline is 3. The description adds meaningful semantics for api_key beyond the schema: it must expose at least one open deposit account and is validated before being stored, plus the security guarantee that it is never logged or echoed.

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: 'Connects the org to Meow from a read-only API key'. It clearly identifies the integration target and the access mode, which distinguishes it from siblings like connect_mercury without needing to inspect the schema.

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

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

It gives clear context on when this applies: a Meow dashboard key, not OAuth, no redirect, and no IP allowlist needed. It does not explicitly name alternatives or exclusion conditions, but the Meow-specific prerequisite is strong enough guidance for a model to choose this over connect_mercury.

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

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

Annotations only declare readOnlyHint: false, so the description carries the burden. It fully discloses that the token is validated against Mercury's accounts endpoint, stored only if valid, that access is READ-only (balances/transactions), that the token is sensitive and vault-encrypted, and never returned/logged/echoed. This goes far beyond the annotation and gives the agent a precise 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?

The description is dense but every sentence earns its place: purpose, authentication method, validation flow, access scope, security, and optional parameter. It is front-loaded with the core function and then layers details, making it easy for an agent to parse quickly.

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 security-sensitive setup tool with four parameters, the description covers all operational aspects: validation, storage, access limits, token handling, and optional webhook. An output schema exists (indicated), so return values are presumably documented elsewhere. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, and the description adds meaning beyond each property's schema description. It explains org_id defaults to the key's org and never needs to be asked, actor_id defaults to the org entity and arbitrary UUIDs are rejected, api_token is sensitive and never logged, and webhook_secret enables live events. This enriches the schema without redundancy.

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 (connects org to Mercury) with a specific mechanism (API token, not OAuth), and clearly distinguishes from siblings like connect_meow and disconnect_mercury by naming the integration target. It leaves no ambiguity about what the tool does.

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

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

It explicitly explains the authentication method (token, no redirect), the validation-and-store flow, and the optional webhook secret use case. It also notes the token is read-only, which implicitly tells the agent this is for setup, not for moving money. The distinction from connect_meow (another integration) is clear via context, and disconnect_mercury is the obvious inverse.

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, idempotentHint=true, destructiveHint=false), the description discloses crucial behaviors: it back-applies to pending events with proper approvals, it matches on a normalised key, it is idempotent, and it can require out-of-band approval returning 'approval_required'. This significantly exceeds what annotations alone 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 dense but well-organized: it leads with the core behavior, then the workflow context, then the write warning, then idempotency, then the guardrail. Every sentence adds information; the only minor issue is the length and the somewhat dense guardrail paragraph, but no sentence is wasted.

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

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

Given the tool's complexity — 7 parameters, an OOB approval guardrail, idempotency, and a back-application behavior — the description covers everything an agent needs to call it correctly: what happens, what to avoid, what to do when approval_required is returned, and what the response statuses mean. The output schema is present, so return values don't need to be spelled out.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds value by explaining how counterparty normalisation affects the counterparty parameter, clarifying that actor_id defaults to the organisation entity, and reinforcing the deprecated confirm parameter's non-bypass behavior. It doesn't add per-parameter detail for every field, but the schema already covers those.

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: 'Creates (or updates) a persistent per-org rule mapping a counterparty to an account, then BACK-APPLIES it to every pending review event from that counterparty.' It clearly distinguishes itself from siblings like update_counterparty_rule and get_pending_by_counterparty by explaining the back-application behavior and the workflow it belongs to.

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 tells when to use this tool: 'This is how you act on get_pending_by_counterparty: "categorise all my AWS as infrastructure" becomes one call.' It also states the guardrail condition and what to do instead ('confirm:true does not bypass it... do NOT retry the call; verify later by re-reading the books'), effectively providing when-not-to-use 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?

Annotations already declare destructiveHint=true, and the description adds valuable context: future events fall back to the static vendor map or review queue, already-booked events are unchanged, and an audit entry is written. This goes beyond the annotations and helps the agent understand 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 compact and front-loaded: it states the action first, then consequences, then audit behavior, then parameter guidance. Every sentence adds value and there is 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?

The description covers the tool's purpose, side effects, audit behavior, and parameter nuances. With an output schema present and annotations covering destructive intent, the description is nearly complete. It could mention idempotency or error cases, but those are not essential for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the optional actor_id default and the org constraint, and by referencing rule_id from list_counterparty_rules. This is useful 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 ('Removes') and resource ('counterparty rule'), and clearly distinguishes it from siblings like create_counterparty_rule and update_counterparty_rule. It also explains the consequence (future events stop auto-classifying), which makes the tool's purpose 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 explains when to use the tool (to remove a counterparty rule) and what happens afterward, but it does not explicitly mention alternatives or when not to use it. The context is clear enough for an agent to select it correctly among siblings, though explicit exclusions would strengthen it.

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

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

Beyond the readOnlyHint=false annotation, the description discloses that the action is audit-trailed and that it only disables the connection, not revokes access. It also explains why (Meow exposes no key-revoke API). This gives the agent a precise expectation of what will and won't happen, which is valuable context not derivable from the annotation 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 two sentences with no fluff. It front-loads the primary action and limitation immediately, and every sentence carries essential information. It is well-structured 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?

With a complete output schema present and the schema fully documenting parameters, the description covers the action, the audit trail, the limitation, and the reason for the limitation. An agent has everything needed to invoke the tool correctly and set user expectations about the outcome.

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 thoroughly documents both parameters (org_id and actor_id), including defaults, constraints, and rejection rules. The tool description adds no additional parameter semantics beyond what the schema provides, 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 clearly states the verb (disables) and the resource (org's Meow integration), and specifies it is audit-trailed. It distinguishes itself from disconnect_mercury by name and from connect_meow by action. The limitation about key revocation adds specificity and prevents misuse.

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 implicitly conveys when to use this tool (when you need to disable Meow) and explicitly warns that it does not revoke the key, directing the user to the dashboard for full revocation. It does not explicitly name alternatives among sibling tools, but the scope is clear enough that an agent knows this is the tool for disconnecting Meow, not a generic disconnect.

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=false annotation, the description discloses that the operation is audit-trailed, that Mercury has no token-revoke API, and that the tool only disables the integration rather than fully revoking access. This gives an agent a realistic model of the operation's side effects and limits.

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 with no filler: the main action is front-loaded and the second sentence earns its place by stating an important limitation. Every word contributes to correct usage.

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 is complete enough for a simple two-optional-parameter tool with an output schema and only one annotation. It covers the critical caveat and side effects, though it stops short of explicitly routing the agent away from sibling disconnect tools.

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 already carry rich descriptions explaining defaults, validation, and when to omit them. The description adds no parameter-specific information, 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 and resource: 'Disables the org's Mercury integration', which clearly identifies what the tool does and separates it from sibling tools like disconnect_meow by naming Mercury explicitly. The caveat about token revocation further clarifies the scope without obscuring the primary 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 implies the tool is used when the org wants to disable its Mercury integration, but it does not explicitly contrast with alternatives such as disconnect_meow or state when not to use it. The token-revocation caveat provides important context, but selection guidance is left mostly to inference from the tool name.

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 provide readOnlyHint=true, and the description goes well beyond that: it discloses live versus ledger-derived provider data, the approximate nature of total_usd_cents, the treatment of pending/unreviewed classifications, and warnings for unqueried providers. 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 core result is front-loaded in the first sentence, and later sentences add non-obvious caveats about provider derivation and pending amounts. The description is long, but almost every sentence carries a substantive behavioral constraint; it could be tightened slightly, but is not bloated.

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 balance endpoint with no required parameters and a rich output schema, the description covers provider behavior, estimate semantics, pending amounts, and warnings. It is complete enough for an agent to call the tool and correctly interpret results without external knowledge.

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 useful meaning for include_providers by explaining which providers are live vs ledger-derived and how 'cash' behaves, which affects parameter choice and result interpretation. It does not significantly extend org_id 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 returns current account balances across the organisation's connected money providers, with a specific resource and scope. However, it does not directly differentiate this from the sibling get_bank_balances, which may also return balances, so it falls short of full sibling differentiation.

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 context is implied: the description explains what balances are returned and provides guidance about interpreting estimates and pending entries, but it never explicitly states when to choose this tool over alternatives such as get_bank_balances or get_financial_summary. There are no exclusion conditions or alternative route names.

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

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

Beyond the readOnlyHint annotation, the description discloses ordering (newest first), append-only nature, pagination semantics (next_cursor null on last page, total_count ignores pagination), and explicitly states that detailed before/after state is never returned. This gives the agent accurate expectations for 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 most important fact (what the tool reads and ordering) is front-loaded, and every subsequent sentence adds operational value: entry fields, use cases, filters, pagination, and the before/after caveat. 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 read-only, zero-required-parameter tool with an output schema, the description covers purpose, filtering, pagination, and output semantics. It gives an agent everything needed to decide to call it and to invoke it correctly, and the output schema covers return structure.

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 adds value beyond the schema by explaining the cursor continuation contract ('next_cursor as cursor; next_cursor is null on the last page'), clarifying how filters combine, and giving a concrete entity_type example. All five parameters themselves are already documented 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?

Description opens with a specific verb and resource: 'Reads the append-only audit trail for an organisation, newest first.' It details the exact entry shape (action, entity_type/entity_id, actor_type, reason, created_at), which makes the tool's purpose unmistakable and differentiates it from transaction- or balance-reading siblings.

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

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

The description gives explicit use cases ('who approved this', 'what happened to event X', 'what has the pipeline done recently') and filter guidance (entity_type/entity_id). It does not name sibling alternatives or state when not to use this tool, so it misses full exclusion guidance but is otherwise clear.

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 readOnlyHint=true already signals safety, the description adds substantial behavioral detail: per-currency sub-accounts collapse into one total, conversion uses today's FX rate, zero-balance banks are included, missing FX rates yield null rather than zero, and residual lines with connection_id null are explicitly not connected banks. This goes far 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 content is dense and valuable, but the structure is one long run-on paragraph with deeply nested parentheticals, making it harder to parse than it should be. It is appropriately sized for the tool's complexity but would benefit from segmentation into purpose, behavior, and 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?

The description covers what the tool returns, how values are computed, how it differs from related reports, edge cases like zero balances and missing FX rates, and explicit routing to the correct sibling. With an output schema present, no return-value detail 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%, so the single org_id parameter is already fully documented with its default and rejection behavior. The description does not add parameter-specific semantics, but the schema alone carries the full meaning, so the baseline of 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 opens with a precise verb and resource: 'Returns the organisation's bank holdings, ONE line per connected bank,' and immediately differentiates itself from the balance-sheet view and from get_account_balance by excluding Stripe and live provider APIs. The naming of Mercury, Revolut, Meow, and Wise, plus the residual Open Banking line, leaves no ambiguity about what the tool returns.

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 NOT to use this tool: 'For live provider API balances or Stripe/cash, use get_account_balance.' It also contrasts this tool's ledger-based, today-FX value with the balance sheet's transaction-date value, giving an agent clear routing criteria among siblings.

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

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

With readOnlyHint=true, the safety profile is already known, but the description greatly exceeds that by detailing every billing state, the meaning of days_until_next_transition, the null behavior for comped accounts, and the fact that books remain safe and ingesting even when walled. It also discloses that payment_url is for humans only.

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 with the core purpose and the never-blocked guarantee. It is long, but nearly every clause adds actionable state or operator guidance; only minor restructuring could improve scannability.

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 an output schema already exists, the description need not explain return values. It completely covers all billing states, transition timing, special comped behavior, and payment instructions, leaving no obvious gap for an agent selecting or invoking 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 coverage is 100%, and the only parameter org_id is already well documented with default behavior and matching constraints. The description does not need to add more, so the 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 identifies the resource as 'This organisation's billing state' and explains that it works in every state and can explain payment_required errors from other tools. This makes it distinct from sibling tools like get_books_status or get_financial_summary, even without naming them.

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

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

It explicitly says the tool is never blocked and should always be used when other tools return payment_required. It also tells the agent exactly what to do in key states, such as telling the operator to subscribe, and warns never to attempt payment completion.

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

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

Goes far beyond the readOnlyHint annotation: 'Reads state only — never calls provider APIs' clarifies side-effect scope, and it discloses the 'all sections are always present' invariant, the gate=true blocking behavior, and the warning never to re-call a refused tool. These are exactly the behavioral traits an agent must know and that annotations alone don't 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?

Dense but every sentence earns its place: loop contract, priority ladder, gate semantics, empty-section meaning, pending-approvals caveat, sibling routing, and read-only note are all high-value. It loses one point because the whole contract is packed into a single run-on paragraph that would be easier to parse with structural breaks.

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 of this complexity — a 9-stage priority ladder, a loop contract, and an interaction protocol — the description is complete. It enumerates every section, defines the termination condition ('done'), explains the gate flag, and notes the output schema exists to handle return-value details. An agent has everything needed to drive the loop 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% and the only parameter (org_id) is fully documented in the schema itself, including guidance to normally omit it. The description adds nothing about parameters, but the baseline 3 applies because the schema carries the full 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+resource ('reports every queue... and next_step') with an unmistakable usage role ('THE loop driver'). It names its sibling (get_onboarding_status) explicitly and states what that sibling is still for, so no agent could confuse the two.

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

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

Gives an explicit loop contract: call first, call after every action, do next_step, call again until next_step.section is 'done'. It also states the exclusion condition ('Supersedes get_onboarding_status, still available for the pure connect walk') and the gate=true waiting rule. Nothing is left to inference.

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

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

The readOnlyHint annotation already covers the safety profile, and the description layers on genuinely non-obvious behavior: historical_import with status 'running' or 'pending' means figures will keep rising and must not be presented as final, and clearing_balances values are explicitly flagged as informational and NOT errors, with the Stripe-only settlement_in_transit accumulation explained. It also warns that a non-zero unreviewed_event_count makes the P&L incomplete. This materially changes how an agent should phrase its answer.

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?

Long, but every sentence earns its place: core composition first, then two clarification clauses that prevent misreading (clearing balances vs errors, in-flight import finality), then routing guidance. The most important operational caveat, 'START HERE... only fall back', is placed prominently and the structure moves from what → caveats → when. 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?

The output schema answers return-value shape, while the description supplies the interpretation layer: what to call out, what to flag as non-final, and what to do next when data is incomplete. Combined with the annotations and sibling list, an agent has everything needed to invoke it correctly and present results responsibly.

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 org_id schema text already explains defaulting, omission, and rejection on mismatch, so the baseline of 3 applies. The tool description adds no parameter-level detail, but none is needed given the schema carries the full burden for the single optional parameter.

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

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

Opens with a specific verb+resource phrase, 'One-call financial snapshot of an organisation', then enumerates exactly what is included: current-month P&L, connected-provider balances, unreviewed_event_count, ledger_sync health, clearing balances, and historical import. It disambiguates against siblings by noting the P&L and balance shapes match get_pnl_report and get_account_balance, and names get_unreviewed_events as the follow-up. There is no ambiguity about what this tool is for.

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

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

Gives an explicit routing rule: 'START HERE for any briefing, health check, or "how are the finances" question; only fall back to the individual tools when you need a different period, specific providers, or the review queue contents.' It also states the follow-up condition ('If unreviewed_event_count is non-zero... follow up with get_unreviewed_events'). The when-to-use and when-not-to-use logic is fully spelled out.

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 carry readOnlyHint=true, and the description extends this substantially: 'Reads connection state only — never calls provider APIs,' which reinforces the safety profile while adding operational specifics. It also discloses degraded-state meaning ('credential rejected by the provider — reconnect required'), the multi-bank connections[] nesting nuance, and the loop-termination rule — all behaviors an agent could not infer from annotations alone. No contradiction with readOnlyHint.

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, roughly 170 words, but every sentence carries load: supersede notice, alternative routing, scope, loop contract, gate meaning, warning handling, and the read-only guarantee. It is front-loaded with the most decision-relevant fact (SUPERSEDED). The length is justified by the protocol complexity, though it demands careful reading rather than offering a quick skim.

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 an output schema exists (so return values need not be spelled out), a single fully-documented optional parameter, and the readOnlyHint annotation, the description covers everything an agent needs: the full loop protocol, termination condition, human-gate semantics, warning handling, degraded-state definition, and the multi-bank structural caveat. The comparison to get_books_status also closes the sibling-selection gap. Nothing material 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%: org_id is fully documented in the schema, including its default, when to omit it, and the rejection condition for mismatched orgs. The description adds no parameter-specific detail, which is acceptable given the baseline of 3 for full coverage. The description's references to next_step.ask, next_step.tool, and next_step.action concern output semantics, not input 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 states a specific function: 'The agent onboarding loop driver: which providers are connected, pending, or degraded... and the ONE next step to take.' It clearly differentiates from the key sibling get_books_status by scoping this tool to the 'pure connect walk' versus 'connections PLUS every books queue.' The SUPERSEDED opening slightly muddies whether the agent should still select this tool, but the subsequent scoping statement resolves that 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?

Explicit routing guidance is provided: 'prefer get_books_status' for the broader coverage, with this tool retained for connect-only walks. The description also lays out a precise loop contract — 'call this, do next_step, call this again — until next_step.action is done' — plus the warning-relay protocol ('relay... VERBATIM and do not proceed without explicit confirmation') and gate semantics. This is exemplary when-to-use and how-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavior: grouping, direction semantics ('inbound = money in, outbound = money out'), aggregate fields, and 'Groups are ordered largest-first'. This goes well beyond the annotation 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?

Three sentences deliver the core purpose, the output contents, the direction semantics, the ordering, and the intended follow-up action. Every sentence earns its place and the main function 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?

For a read-only summary tool with one optional parameter and an output schema, this description is complete. It tells the agent what the response contains, how it is ordered, and how to act on it, leaving no critical gap.

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

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

Schema description coverage is 100% and the only parameter, org_id, is fully documented in the input schema. The tool description adds no extra parameter-level meaning, so the 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?

States a specific verb and resource: 'Summarises the review queue clustered by counterparty and direction'. It also explains the exact grain ('the exact grain a rule is keyed on'), which clearly distinguishes it from per-transaction review tools like get_unreviewed_events.

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 gives the usage pattern: read this summary to decide once per vendor, then call create_counterparty_rule to categorise a whole counterparty. It contrasts this with deciding 'per transaction', so an agent knows when this tool is the right choice.

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 the description adds substantial behavioral detail: exclusion of unclassified events with warning, multi-currency handling (null combined fields, per-currency breakdown), sign conventions, and derived profit fields. This goes well 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 long but every sentence conveys important information—purpose, exclusions, derived fields, usage alternative, and multi-currency edge case. It is well-structured with a clear MULTI-CURRENCY section, though slightly dense.

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 (multi-currency, exclusions, derived metrics) and the presence of an output schema, the description is remarkably complete. It explains return fields, sign conventions, the unclassified_cents warning, and the multi-currency 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%, so each parameter is already well-documented. The description adds context like 'over a date range' and explains multi-currency behavior for currency, but this largely mirrors the schema's param descriptions. Baseline 3 is appropriate since the description doesn't significantly add 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?

Clearly states the tool generates a profit & loss report for an organisation over a date range, with specific metrics listed. It explicitly differentiates from get_financial_summary by noting it is for period-based questions versus a current snapshot.

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: 'Use this for "how did we do in <period>" questions; for a full current snapshot prefer get_financial_summary.' Also notes that unclassified events are excluded and approval via approve_classification may be needed, implying when to use after classification.

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 repeats 'Read-only', matching the annotation, but adds meaningful behavior beyond it: journal lines are null when not yet booked, and provenance/evidence documents are included. It accurately reflects the read-only nature and introduces useful null-state 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 front-loaded with 'full story' and presents a compact field list, then a focused line about transaction_id provenance. It is slightly long but all clauses contribute meaningful information; only 'Read-only' is redundant with the annotation.

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 an output schema present, return values do not need extensive explanation, and the description still covers the null-booking behavior and the origin of transaction_id. Combined with the annotation and schema, including org_id defaults and rejection rules, the agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 wagered. The description adds value by defining transaction_id as a classified event id and listing the exact upstream tools that can provide it, which the schema alone does not convey.

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 identifies the resource as a single transaction/classified event and enumerates what it returns. It separates this tool from sibling list/summary tools by emphasizing 'full story of one transaction', making its purpose 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?

It explicitly states where transaction_id comes from (get_unreviewed_events, list_documents matched_event_id, or a proposal candidate), which tells an agent when this tool is the next step. It does not name an alternative tool to use instead for other purposes, but the single-transaction framing provides sufficient 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?

Annotations only declare readOnlyHint=true, and the description adds substantial behavioral context beyond that: the events are not yet synced to the ledger, the pipeline is paused for them, and they are excluded from P&L reports until approved. It also reveals what fields each item carries so the agent knows this is a zero-further-query consumption pattern. 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 but every sentence earns its place: definition, business impact, payload contents, resolution path, and pagination. It is front-loaded with the core purpose and maintains high signal-to-noise throughout with no filler.

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

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

Combined with the 100%-covered input schema, an output schema, and the read-only annotation, the description leaves nothing essential missing. An agent knows what the tool returns, why it matters, how to paginate, and what sibling tool to call next.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds real value by explaining how cursor relates to next_cursor for pagination, how limit and total_count interact, and how org_id defaults to the authenticated API key's organisation, which goes beyond the schema's basic 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: it lists classified events that the rules engine could not confidently categorise, with needs_review = true and not yet synced to the ledger, ordered newest first. It clearly distinguishes this from generic list tools by tying it to the review/approval workflow and naming the exact condition that defines the set.

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

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

It explains when this queue matters: the pipeline is paused for each event, and they are missing from P&L reports and the ledger. It also gives the explicit next action by directing agents to approve_classification with classified_event_id and the correct category, and explains pagination via next_cursor.

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 provide readOnlyHint=true, and the description adds meaningful context beyond that: it discloses that protected system accounts are rename-only, that the tool shows QuickBooks provisioning status, and that the org_id must match the key's org or the request is rejected. This goes beyond the annotation's basic read-only signal.

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

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

The description is a single, information-dense sentence that front-loads the core purpose, then lists the returned fields, then gives usage guidance. Every clause earns its place; there is no fluff or repetition of the title.

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

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

For a read-only list tool with one optional parameter, a rich output schema, and a clear usage directive, the description is complete. It tells the agent what it will get, when to use it, and the one parameter caveat. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and the schema already documents org_id well. The description adds value by explaining when to omit org_id and that it defaults to the authenticated key's org, which reinforces the schema's guidance. It doesn't need to add more since there's only one parameter and it's fully documented.

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 ('Lists') and resource ('this org's chart of accounts') and enumerates exactly what fields are returned (code, name, type, P&L rollup bucket, protected status, active status, QuickBooks provisioning status). It also distinguishes itself from sibling mutation tools by explicitly saying to use it before add/rename/deactivate.

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 'Use this before add/rename/deactivate to see current codes and statuses,' which tells the agent when to invoke this tool versus the sibling mutation tools. It also clarifies the org_id parameter behavior, saying it normally should be omitted and never needs to be asked from the user.

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, so the safety profile is covered. The description adds meaningful behavioral context: the rules are persistent, auto-classify future events, and skipping review is a consequence of the learned map. It also clarifies the direction field semantics (inbound/outbound/null = both), which is beyond what annotations provide. Minor gap: no mention of pagination or ordering, but not critical for a list 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?

Three sentences, each earning its place: the first defines the resource and its purpose, the second enumerates the returned fields, and the third routes to sibling tools. Information is front-loaded and there is zero 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 tool is a simple read-only list with one optional parameter, a rich output schema, and full schema coverage. The description explains the domain significance (learned vendor map, skip review), the returned fields, and the modification alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter org_id is fully documented in the schema, including its default and the fact that it can be omitted. The description reinforces this by saying 'you normally omit it and never need to ask the user for their organisation UUID' — adding practical guidance beyond the schema. Baseline 3 is exceeded because the description adds real usage nuance.

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 ('Lists') and resource ('the org's persistent counterparty rules'), and immediately distinguishes it from sibling tools by explaining what the rules do (auto-classify future events so they skip review). It also names sibling tools update_counterparty_rule and delete_counterparty_rule, 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 explicitly says when to use this tool (to view the learned vendor map) and names the alternatives for modifying rules (update_counterparty_rule, delete_counterparty_rule), noting they affect future classification only. This gives clear routing guidance without needing to inspect sibling schemas.

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 meaningful behavior: documents never create bookings, results are limited to the newest rows, total_count may exceed files.length, and match_ambiguous items await a decision with proposal details. This gives the agent crucial expectations about side effects and pagination that annotations alone do not convey.

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

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

The description is dense but every sentence and clause carries useful information, from the row definition to the status pipeline to the no-booking guarantee. It is front-loaded with a plain statement of what the tool does before diving into status semantics.

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-and-filter tool with an output schema, the description is complete enough to call correctly: it covers result ordering, limit cap, status filters, proposal resolution, and side-effect constraints. The agent knows how to navigate the result set and what follow-up action to take.

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 substantially expands parameter meaning. It explains each status enum value in pipeline terms, details proposal.reason values such as multi_candidate and dkim_fail, and clarifies the limit's 'newest first' behavior and capped maximum.

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: 'Lists the organisation's captured documents', clarifying each row is a stored artifact and that results are newest first. It distinguishes the tool's role from bank-record tools by stating documents are evidence and 'NEVER create bookings'.

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 operational guidance: use the status filter to reach older rows beyond the newest limit, and resolve match_ambiguous proposals by calling attach_document. It does not explicitly name sibling tools to avoid, but the workflow context is strong enough for an agent to know when this listing tool is appropriate.

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 signal read-only, idempotent, and non-destructive behavior, and the description adds meaningful context: matches are limited to the org's own connected banks, must be outflow-plus-inflow pairs, and the endpoint excludes auto-booked same-currency high-confidence matches. This goes beyond what annotations alone provide 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 dense but every sentence earns its place: core return semantics, the matching criteria, the two follow-up actions, and the exclusion of auto-booked pairs. It is front-loaded with the primary purpose and avoids 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 one-parameter, read-only listing tool with a full output schema and clear annotations, this description is complete. It tells the agent what the list contains, what is excluded, what to do with the results, and which sibling tools are relevant. No essential selection or invocation information 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 only parameter, org_id, is fully documented in the schema with its default behavior and validation requirement. Since schema description coverage is 100%, the description does not need to compensate, and the baseline of 3 applies. The main tool description adds no additional parameter-level information, but none is 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 identifies a specific operation: returning inter-bank transfer matches awaiting confirmation, and clarifies the exact shape of those matches (outflow on one org-owned bank plus inflow on another). It distinguishes this read-only listing from the related confirm_transfer and reject_transfer actions and from auto-booked high-confidence pairs, so an agent can accurately separate it from siblings.

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

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

The description clearly frames when this tool is relevant: the ambiguous set that needs human confirmation, with high-confidence same-currency pairs explicitly excluded. It also directs the agent to confirm_transfer and reject_transfer as follow-ups. It does not explicitly name alternative listing tools such as get_pending_by_counterparty or get_unreviewed_events, 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?

The annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes far beyond this by disclosing exactly what changes and what does not: amount/currency/date are immutable, journal lines are rebuilt by relabelling the primary leg, balances are preserved, an audit_trail entry is written, and a ledger sync is re-queued. It also states the guards and side effects of create_rule, giving full behavioral transparency.

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. It is front-loaded with the core purpose, then flows logically through invariants, guards, the create_rule option, and actor_id defaults. The uppercase 'GUARDS' label structures the constraints clearly, and there is no filler or redundancy.

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

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

Given the complexity (6 parameters, multiple guards, side effects), the description is complete: it explains preconditions, failure modes, side effects (audit, ledger sync, rule creation), parameter defaults, and validation. The presence of an output schema means return-value details are not needed, and the description covers everything an agent needs to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it reinforces that there are no parameters for amount/currency/date and restates create_rule's forward-only behavior, but the schema already documents defaults, validation, and the chart-of-accounts values. No new parameter semantics are introduced.

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

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

The description names a specific verb and resource: 'Changes the ACCOUNT on an already-posted entry (from the general ledger) and nothing else.' This clearly differentiates it from siblings like approve_classification (which handles unreviewed entries) and create_counterparty_rule (which creates forward rules without editing entries).

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 and when-not-to-use guidance: 'the entry must be posted (not awaiting review — use approve_classification for that); a manual or multi-leg entry cannot be reclassified (correct it by reversal); and an entry in a CLOSED period is refused (reopen or post a prior-period adjustment).' It also clarifies create_rule's relationship to counterparty rules, so an agent can route correctly.

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 idempotentHint annotation, the description reveals key behaviors: events already present are skipped, the P&L is never double-counted, an overlap_warning is returned unless confirm_overlap is true, and a reconciliation sweep may drain Stripe payouts from clearing. This adds substantial operational 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?

The description is information-dense but every sentence earns its place: purpose, idempotency/safety, overlap behavior, side-effect sweep, and follow-up action. It is well-structured and front-loaded with 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?

The description covers what the tool does, when it is safe to call, edge cases, side effects, and how to monitor progress. With an output schema present, the return-value discussion is not necessary, and no critical operational details are 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 schema already covers all parameters with descriptions, so the baseline is 3. The description adds meaningful context by explaining what happens on overlap, the purpose of confirm_overlap as a 'did you mean to re-scan?' prompt, and the data scope for providers. This exceeds minimal 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 'queues a historical import' over a chosen window and specifies the data sources (Stripe charges/refunds/payouts, Mercury transactions). It names the affected resource and distinguishes this as a re-import operation from the initial connect tools in the sibling list.

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 says 'safe to call any time', explains idempotency, and gives concrete guidance on overlap behavior with confirm_overlap. It also tells the agent to poll get_financial_summary for progress, but it does not explicitly contrast this tool with an alternative for live or initial sync.

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 annotations are all false, so the description carries the behavioral burden. It discloses non-obvious side effects: the two events remain in the normal review queue and can be re-matched later. It also clarifies the default actor attribution and the precondition that the link must belong to the org's suggested matches.

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-loads the core behavior and effect, and contains no filler. The guard is placed immediately after the usage guidance, making the most important constraint prominent.

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 rich schema descriptions, the output schema, and the annotations, the description covers the key contextual aspects: what happens to the events, when to call it, and the critical precondition. Nothing essential is missing for an agent to decide whether and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by introducing the GUARD that link_id must be one of the org's suggested matches, and by restating that actor_id defaults to the organisation entity. This gives the agent a correctness precondition not fully captured by the schema alone.

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 ('Marks a suggested match as NOT a transfer') and explains the consequence for the two events, which clearly sets it apart from confirm_transfer and other classification tools. It states exactly what the tool does without relying on vague phrasing or echoing the title.

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 trigger condition: 'Use this when the matcher paired two genuinely unrelated transactions.' It also adds a guard about the link being the org's suggested match, which prevents misuse. It does not explicitly name the alternative confirm_transfer, but the context and wording make the choice reasonably clear.

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 the annotations: the account code is unchanged, the new name syncs to QuickBooks under certain conditions, existing transactions are not recategorized, the operation is audit-trailed, and actor_id attribution is constrained. This goes well beyond the readOnly/idempotent/destructive hints and does not contradict them.

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

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

The description is compact and front-loaded: it states the purpose first, then key invariants, side effects, and attribution behavior. Every sentence carries meaningful operational information without redundancy.

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

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

Given the complete parameter schema, the output schema, and the annotations, the description covers the important side effects, invariants, and attribution model. There is no significant missing context needed 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 input schema already documents all five parameters with descriptions, defaults, and constraints, so the baseline is 3. The description reinforces actor_id semantics but does not add significant meaning beyond the schema's 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 clearly identifies the action ('Renames') and the resource ('a chart account'), and adds scope ('system or not') plus the key invariant that the account code never changes. This is specific enough to distinguish it from sibling tools like add_chart_account, set_chart_account_active, and list_chart_accounts.

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 useful context about what the rename does and does not affect, but it does not explicitly state when to choose this tool over rename-related siblings or when not to use it. The intended use is implied by the name and description rather than made 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?

Annotations already indicate a non-read-only, non-destructive, idempotent operation, and the description adds substantial behavioral detail beyond that: deactivation never deletes, existing transactions remain visible in the P&L, refusal conditions, audit-trailing, and actor_id attribution constraints. 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?

Three dense sentences carry all the essential information with no filler. The description is front-loaded with the primary action and effect, then covers constraints and parameter edge cases. 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?

Given the output schema exists, the description does not need to explain return values. It covers the tool's core behavior, non-destructive nature, refusal cases, audit trail, and the actor_id safeguard. Together with the schema and annotations, an agent has everything needed to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the real-world effect of active=false, the refusal conditions tied to account_id, and the audit-trail implication of the reason parameter. This extra context pushes it above baseline.

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

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

The description states a specific verb ('deactivates'/'reactivates') applied to a specific resource ('a chart account'), and immediately clarifies the operational meaning of deactivation. This distinguishes it clearly from sibling tools like rename_chart_account or add_chart_account.

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 context on when this tool applies: to hide or unhide a chart account from new categorisation. It also states explicit refusal conditions for system accounts and accounts referenced by counterparty rules. However, it does not explicitly name alternative siblings or say 'use X instead when...', 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?

Adds significant behavioral context beyond annotations: future-only classification, no re-categorisation of booked events, audit trail side effect, and idempotence as a no-op. These details are essential for an agent to understand the tool's real-world effects and are not conveyed by the 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 information-dense and front-loaded with the core action, then efficiently covers key side effects and edge cases. Every sentence contributes unique behavioral or param guidance, with no filler or repetition.

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

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

With an output schema present and 100% parameter coverage, the description adds all necessary behavioral context: side effects, scope, idempotence, and actor defaults. 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?

Schema description coverage is 100%, so the schema fully explains all five parameters. The description adds no parameter meaning beyond what the schema already provides; it merely restates actor_id's optionality and org-binding, which is already documented.

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

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

States the specific verb ('Changes') and resource ('target account of an existing counterparty rule'), making it immediately distinct from create_counterparty_rule and delete_counterparty_rule. The title further reinforces the re-pointing action 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?

Clearly implies this is for modifying an existing rule's target account and not for creating or deleting rules. It does not explicitly name alternatives or provide when-not-to-use scenarios, but the context is clear enough for an agent to select it correctly.

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