stub

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the additive, non-destructive nature is covered structurally. The description adds nothing beyond that: it doesn't say placement behavior, whether the call returns the created tile or its coordinates, or whether a duplicate tile of the same type is rejected.

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?

One short, front-loaded sentence with zero redundancy, so there is no padding to cut. The problem is the opposite of verbosity: the sentence is sized far below what a mutation tool with a nested payload object needs.

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

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

For a write tool with a free-form nested `tile` object, no output schema, and only 50% parameter coverage, the definition should explain where valid tile types come from and what the call yields. None of that is present, so an agent must call it largely blind.

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

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

Schema coverage is 50%: the `tile` property carries a genuinely rich description covering defaults and the new-row-at-bottom fallback, but `dashboardId` is documented nowhere. The description neither compensates for that gap nor adds any constraint or format hint 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?

"Add one tile to a dashboard" gives a verb and resource, so the basic action is identifiable, and "one" signals singular-per-call. But it is essentially the tool name and title restated, and it draws no line against update_dashboard_tile, remove_dashboard_tile, create_dashboard, or list_dashboard_tile_types, all of which live in the same sibling 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?

There is no when-to-use guidance at all: nothing says when to add versus update an existing tile, whether a tile type must first be discovered via list_dashboard_tile_types, or whether the dashboard must already exist. An agent has to infer the workflow entirely from the tool list.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the additive, non-destructive nature is already structured. The description adds only that the line attaches to an existing document item identified by id, and repeats no permission, resolution, or failure behavior that the schema doesn't already spell out.

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

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

Two short sentences, front-loaded with the operation and the attachment scoping, then the sibling relationship. No filler and every sentence carries information.

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

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

For a 15-parameter, zero-required mutation tool with no output schema, the description is thin: it doesn't explain what is returned or what happens when the parentid match is ambiguous (that lives only in the schema), nor does it warn that omitting the document id would fail. The rich schema and annotations carry most of the load, leaving this adequate but not complete.

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

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

Schema description coverage is 100%, so all 15 parameters including the tricky resolution rules for parentid, the decimal-fraction rate, and the invoice/invoiceid/quinvoice aliases are documented in the schema. The description adds only the item-id lookup hint, so the baseline 3 applies.

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

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

States a precise verb (Add) plus the resource (a sales-tax/VAT line) and the exact attachment target (a single line item on an invoice/quote/credit/debit note). It explicitly names the complementary sibling update_document_item_salestax, so an agent can separate the two without opening a schema.

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

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

"Pairs with update_document_item_salestax" tells the agent this is the create-side of the salestax-line pair and that update is the alternative for existing lines. It gives clear context but no explicit exclusions or comparison against the other tax siblings such as add_entity_salestax.

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 this is a non-read-only but non-destructive write, so the safety profile is covered. The description adds the meaningful constraint that the parent document must already exist and that only one line is added per call, but leaves the richer behavioral details (expense copying, VAT treatment, billedon warnings, optimistic concurrency) to the schema's own parameter text.

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

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

A single sentence with the core action front-loaded followed by the two disambiguating alternatives. Every clause earns its place; no filler.

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

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

For an 18-parameter mutation with no required fields and no output schema, the description supplies the routing and scope an agent needs, and the schema documents every parameter. It stops just short of flagging the mutation's side effects or which parameters matter for common cases.

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

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

Schema description coverage is 100% across all 18 parameters, so the schema already carries naming, currency, id and concurrency semantics. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a precise verb and resource (add ONE line to an EXISTING document) and names the document types it applies to. It also explicitly distinguishes itself from save_document and update_document_item, so the agent can route without inspecting sibling schemas.

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

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

Gives explicit when-to-use plus two named alternatives with the condition that selects each: save_document for creating the document, update_document_item for modifying an existing line. Nothing is left to inference.

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

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

Annotations indicate a write operation (readOnlyHint=false, destructiveHint=false), but the description adds no behavioral context beyond the action itself. No mention of side effects, prerequisites, or how the addition affects existing tax calculations.

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 short sentences, front-loading the primary purpose and then providing a concise usage alternative. No wasted words.

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

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

For a single-add tool with a rich schema and clear sibling distinction, the description is sufficient. It states the purpose and usage guidance; the schema covers parameters. A slightly more detailed behavioral note would be nice, but not essential.

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

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

The input schema has 100% parameter description coverage, so the description does not need to explain parameters. The baseline of 3 applies; the description adds no extra meaning beyond the schema.

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

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

Clearly states the action: 'Add a sales tax to an entity.' The verb 'add' and resource 'sales tax' are specific, and the mention of the plural sibling add_entity_salestaxes distinguishes it from the batch operation.

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 guides when to use this tool vs. the alternative: 'To add several taxes at once, prefer add_entity_salestaxes.' This tells the agent to use this tool for a single tax addition, which is a clear usage direction.

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?

Describes non-deduplication ('does not deduplicate... adds another copy') and error behavior ('returns an {:error true} map rather than throwing'), providing useful insights not present in the sparse 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?

Four sentences, each carrying essential information with no filler: purpose, deduplication behavior, error handling, and alternatives.

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?

Covers core behavior, edge cases (duplicate ids, missing entity), and alternative routes, but does not specify the success return value; however, no output schema is provided, so this is a minor gap.

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

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

Schema descriptions fully cover all three parameters (entity, entityid, taxids) with clear meanings; the tool description adds no extra parameter detail beyond what the schema already provides.

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

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

Clearly states it adds multiple sales taxes to one entity by their ids, and distinguishes from sibling tools (add_entity_salestax for a single tax, add_salestax_to_entities for applying one tax across many entities).

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

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

Explicitly names alternative tools and when to use them: 'To add a single tax to one entity use add_entity_salestax; to apply one existing tax across many entities use add_salestax_to_entities.'

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 this is a non-read-only but non-destructive mutation, and the description usefully clarifies that it appends a single line rather than replacing anything. It says nothing about preconditions an agent would care about though — whether the parent entry must be in an open/unlocked period, what happens if the entry does not exist, or whether debit/credit must balance at line level.

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

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

A single front-loaded clause establishes the operation and its scope, then the same sentence names both alternatives — no wasted words and no burying of the key constraint.

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

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

For an eight-parameter tool with zero required parameters, the description never indicates the minimum viable call (entryid plus accountid plus one of debit/credit), which is a real risk of a malformed invocation. It is otherwise complete given full schema coverage and the absence of an output schema.

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

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

Schema coverage is 100%, so the schema already explains all eight fields in detail, including the $delete sentinel and the clientid/supplierid mutual exclusion. The description only implies that a line carries a debit or credit amount; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (add ONE debit or credit line) plus a hard scope constraint (to an EXISTING journal entry), which immediately separates it from entry-creation and line-editing siblings.

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

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

Explicitly routes to save_journal_entry for a whole new entry and update_journal_line for changing an existing line, so the when-to-use and when-not-to-use conditions are both 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 already indicate this is a write operation with no destructive intent. The description adds that it works as a single transaction and applies an existing tax definition, but it does not disclose potential side effects such as overwriting existing tax assignments or partial failure behavior.

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

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

The description is concise, uses only two sentences, and front-loads the core purpose. Every clause adds relevant information, with no filler or redundancy.

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

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

For a simple bulk update tool, the description provides sufficient context: what it does, what it applies to, and what it does not support. No output schema is present, so return-value details are not required, though a note on success/failure behavior could make it slightly more complete.

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

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

The schema descriptions fully cover all three parameters with clear meanings. The tool description mostly restates the schema rather than adding new semantic detail, such as constraints on tax IDs or behavior when multiple entity IDs are invalid.

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

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

The description clearly states a specific action: applying one existing sales tax to several income or expense records in a single transaction. It also explicitly distinguishes this tool from invoice/bill line-item tax handling, 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?

The description gives clear usage context by specifying that invoices/bills use line-item tax and are not supported here. It implies the appropriate alternative for those cases, though it does not explicitly name a sibling tool.

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

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

Annotations already cover readOnlyHint=false and destructiveHint=false. The description adds no behavioral details beyond the basic action, such as side effects, error conditions, or return values. It is consistent with the annotations but does not go beyond them.

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

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

The description is a single, clear sentence that is concise and well-structured. It avoids unnecessary words and effectively communicates the tool's 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 tool is relatively simple with three required parameters, all described. However, the description omits any mention of output or success/failure feedback, which could be important for an agent to confirm the attachment process. It is adequate but not fully comprehensive.

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

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

The schema provides 100% coverage for all three parameters with clear descriptions. The tool description itself adds no additional parameter semantics, so the baseline score applies.

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

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

The description clearly states the action: attaching a file to an entity, with examples like invoice and expense. It is specific and distinguishes from file-related sibling tools such as list_files or remove_file.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It lacks context about prerequisites (e.g., file must be uploaded first) and does not contrast with other file operations.

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 destructiveHint=true, and the description adds the specific destructive scope: it clears all tags from one entity. This goes slightly beyond the annotations but does not disclose additional behaviors such as irreversibility or effects on related 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 a single front-loaded sentence with no wasted words. It communicates the core operation efficiently.

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

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

For a simple two-parameter tool with no output schema, the description, full parameter descriptions, and destructive annotation are largely sufficient for an agent to select and invoke the tool correctly. It lacks only a brief mention of related set operations or consequences.

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%: both 'entity' and 'entityid' are described with examples. The description adds no additional parameter meaning beyond what the schema already provides, 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 states a specific verb ('Clear') and resource ('all tags from an entity'), clearly distinguishing it from sibling tools like set_entity_tags or set_entity_tags_bulk. The scope (all tags) is explicit.

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?

No guidance is given on when to use this tool versus alternatives such as set_entity_tags, set_entity_tags_bulk, or delete_tag. The description only states what it does, not when an agent should choose 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 annotation, the description explicitly states 'READ-ONLY: it converts, never records anything' and details the exact return fields, future-date handling, and the no-rate error shape. This gives an agent a clear behavioral model without needing to call the tool or inspect external docs. There is no contradiction with the annotations.

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

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

The description is a single dense paragraph of roughly 100 words, front-loaded with the core action and rate source before optional arguments and edge cases. Every sentence serves a purpose, and the READ-ONLY note, while echoing the annotation, is a useful reinforcement rather than fluff.

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

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

Since there is no output schema, the description takes on the burden of documenting the return object, and it does so explicitly: amount, from, to, converted, rate, ratedate, and optional within_tolerance. It also covers the no-rate error case, tolerance bounds, and the connection to find_candidate_transactions, so an agent has all information needed to call the tool correctly.

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

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

The schema already covers 100% of parameters, but the description adds meaningful semantics it does not: target is explained as an amount in the 'to' currency such as a bill's balance, tolerance is tied to the default 3% cross-currency matching band, and within_tolerance behavior is defined. This enriches the parameters beyond the structured schema.

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

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

The description opens with 'Convert an amount between currencies at the OpenExchangeRates rate for a date', giving a specific verb, resource, and rate source. It is immediately distinct from sibling tools like find_candidate_transactions and any ambiguity about what action is performed is eliminated. It even specifies the return payload.

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

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

The description provides clear usage context: it uses 'the same dated rate find_candidate_transactions matches with' and explains how the target and tolerance parameters are meant for checking bill balances within the 3% cross-currency matching band. It does not explicitly state when not to use the tool or name a direct alternative, but the context is sufficient for an agent to select it for conversion checks.

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 safety is covered; the description adds real behavioral context beyond that, notably that the facts are 'each confirmed by the owner' (a data-provenance signal) and that the key list includes 'common keys still empty'. It does not describe the return shape in any structured way, which matters since there is no output schema.

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

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

Three sentences, front-loaded with the read action, and the exclusion is saved for last as a routing cue. The middle sentence is a run-on that tries to cover two distinct outputs (custom facts and the key list) in one breath, and 'stub has no other field for' costs the reader a re-read.

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

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

With no output schema and no parameters, the description carries the burden of explaining what comes back, and it does list the returned content (owner-confirmed facts, all keys used, empty common keys). Naming the excluded fields and where to get them closes the main gap. What is missing is any sense of the shape or size of the fact list.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter claims are made.

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 clear verb+resource ('Read the business's profile') and grounds it with concrete examples (accountant, B-BBEE level, CSD number, lease end) plus a second function, listing the business's keys. It distinguishes itself from the sibling get_business_profile by explicitly excluding VAT/registration/payroll numbers. The phrasing 'concrete facts stub has no other field for' is awkward jargon that slightly muddies an otherwise clear purpose.

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

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

Explicitly routes the agent elsewhere for tax identifiers ('The VAT, registration and payroll numbers are not here: read them with get_business_profile'), which is exactly the kind of alternative-naming that prevents mis-selection. It also gives a rationale for the key listing ('so you reuse one rather than name a new one'). It stops short of a full when-to-use/when-not matrix against the other profile-ish siblings such as get_business_overview.

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=false and destructiveHint=false, and the description consistently describes a create operation. It adds useful domain context about chart-of-accounts accounts, but does not disclose validation behavior, duplicate handling, required logical fields, or authorization needs beyond what annotations and schema already provide.

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

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

Two compact sentences, front-loaded with the core action and immediately followed by the sibling disambiguation. Every clause carries useful selection or scoping information.

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

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

For a create tool with 15 optional parameters and no output schema, the description supplies enough domain and sibling context to select the tool correctly, while the schema carries the detailed field semantics. It could be stronger with a note about duplicate or empty-account behavior, but it is largely complete for 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 explains all 15 parameters thoroughly. The description adds no parameter-specific semantics beyond naming account categories generally, 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 gives a specific verb and resource: create a chart-of-accounts ledger account, and enumerates the account categories it covers. It also explicitly distinguishes this from create_bank_account, so an agent can select it without opening sibling schemas.

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

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

It explicitly directs bank-account creation to create_bank_account, which is the most likely sibling confusion. However, it does not say when to create a new account versus update_account or list_accounts, nor does it mention prerequisites such as duplicate-code handling.

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 non-destructive write, and the description adds transparency by noting that the 'amount' field is ignored and that legacy link fields should be avoided in favor of dedicated endpoints. This gives the agent a realistic expectation of 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 a single well-structured paragraph that leads with the core purpose, then gives usage context and clarifies legacy vs. preferred fields. It avoids redundancy and is appropriately sized for the tool's complexity.

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

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

Given the absence of an output schema, the description sufficiently covers what the tool does and key behavioral nuances (disposal, depreciation defaults, legacy fields). It doesn't enumerate every parameter, but the schema does, so the combination is complete.

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

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

All 18 parameters have descriptions in the schema, and many include additional semantic context (e.g., depreciation type examples, default for disposeddate, decimal format for rate). This goes beyond basic parameter listing, helping the agent choose correct values.

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 creates a new fixed asset, elaborates on what qualifies as an asset, and distinguishes it from update/delete operations. It also explains the core behavior of linking to the originating expense for cost basis.

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 guidance on when to use the tool (recording a capital purchase to depreciate) and references alternative endpoints for unlink operations. It could be slightly more explicit about not using it for non-capital expenses, but the context is clear enough.

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

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

Annotations already establish write semantics (readOnlyHint=false, destructiveHint=false), so the description only needs to add context. It does add the useful framing that this is a real bank account used for reconciliation and cashflow, but says nothing about what side effects creation triggers (ledger account minting, opening balance handling) or how the upsert-by-`id` behavior works.

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

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

A single front-loaded sentence with a disambiguating parenthetical; nothing is wasted and the most important distinction arrives before any detail.

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 22-parameter creation tool with intricate opening-balance, currency and ledger-linking behavior, the description itself is thin and leaves all of that to the schema. Because the schema is exhaustive and there is no output schema to explain, this is adequate but does nothing to help an agent anticipate the tool's real complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all 22 parameters including the complex confirm, accountid, openingrate and clearopeningbalance semantics. The description adds no parameter-level meaning beyond what the schema already provides, which is the baseline 3 case.

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 ("Create a new bank account for the business") and immediately disambiguates it from the nearest confusing sibling by clarifying it is a real money-movement account, not a chart-of-accounts ledger account. An agent can distinguish it from create_account without opening either schema.

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

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

The exclusion ("Not a chart-of-accounts ledger account") gives a clear negative-use signal that implicitly routes chart-of-accounts work to create_account. However, no alternative is named explicitly, and nothing says when to use this versus update_bank_account or update_bank_account_currency, despite the schema's `id` param mentioning updates.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does it well: partial success, dedup-by-name matched rather than double-added, blank-field fill-only, per-row refusals isolated in errors, and error=true only when nothing was created or matched. The only gap is that side effects on matched records (which blank details get written) are described only loosely.

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

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

Front-loaded with purpose, batch limit, and the return shape, then behavior, then the confirm requirement, then the alternative. It is dense but every sentence carries a distinct fact; the return-object rendering makes one sentence heavier than it needs to be.

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 single-parameter bulk-write tool with no output schema, the description supplies what is missing: batch ceiling, what the returned object contains, how matched versus created versus refused rows differ, and the human confirmation step. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema coverage is 100%, so the nested row fields are already fully documented. The description adds operational meaning by framing items as file-ordered rows and by explaining that `line` is echoed into results so a refusal can be traced back — useful, but the bulk of parameter meaning already lives in the schema, so baseline 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?

Opens with a specific verb and resource plus scope: "Create many customers from a list", and immediately names the sibling workflow it pairs with (read_file_rows) and the sibling it is not (save_client for changes). An agent can distinguish it from list_clients and save_client without opening any schema.

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

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

Gives explicit routing: use save_client to change an existing customer, call again with the next page beyond 100 rows, and show a preview plus get one confirm before calling. That is a when-to-use, a when-to-use-differently, and a prerequisite in three sentences.

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=false and destructiveHint=false, so the write-but-not-destructive profile is covered. Beyond that the description adds only the optional-tiles capability; it says nothing about response contents (e.g. the created id) or about the overwrite-via-repeated-id behavior, which the schema carries instead.

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

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

A single economical sentence with the action and the optional scope front-loaded; there is no filler, hedging, or repetition of schema content.

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

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

For a mutation tool with no output schema, an agent would benefit from knowing what comes back (the dashboard object or its id) and whether tile ids must be unique within the request. The description is accurate but thin relative to the tool's nesting and creation semantics.

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

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

Schema coverage is 75%, so the schema already explains the id overwrite semantics, the name, and the tile shape with a pointer to list_dashboard_tile_types. The description contributes only the word "optionally" for tiles (tiles are indeed not required) and adds no format or constraint detail beyond the schema.

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

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

"Create a custom dashboard, optionally with its tiles" states a specific verb and resource, and the word "create" cleanly separates it from update_dashboard, get_dashboard, and list_dashboards. It stops short of naming those siblings or clarifying the relationship to add_dashboard_tile.

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

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

The phrase "optionally with its tiles" implies the agent may bundle tiles into creation rather than calling add_dashboard_tile afterwards, which is an implied routing hint. There is no explicit when-to-use/when-not guidance, no mention of when update_dashboard is the better call, and no stated prerequisites.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the basic write-but-not-destructive profile is covered. The description adds useful context about organizing uploaded files, but it does not disclose behaviors like duplicate-name handling, ID generation, or return values. That is acceptable but not exceptional given the annotations.

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

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

Two sentences, no filler. The primary action is front-loaded, and the second sentence provides a valuable routing pointer to update_folder without wasting words.

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

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

For a simple two-parameter create tool with full schema coverage and non-destructive annotations, the description is sufficient. It clearly states the purpose, covers the main alternative, and no critical missing context blocks invocation. A small gap is the absence of return-value or duplicate-handling guidance, but this is not severe for such a straightforward tool.

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

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

Schema description coverage is 100%, so the input schema already fully documents 'name' and 'parentid'. The description adds marginal conceptual context through 're-parent' but does not meaningfully enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb and resource ('Create a new folder') and adds purpose context ('organising the business's uploaded files and documents'). It also distinguishes itself from update_folder by explicitly reserving rename/re-parent operations for that sibling.

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

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

The description states exactly when to use this tool (creating a new folder) and gives an explicit alternative for existing folders: 'To rename or re-parent an existing folder use update_folder instead.' This leaves no ambiguity about tool selection.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing all-or-nothing transaction semantics, the top-level transactionid inheritance with per-item override, the special meaning of an expense accountid pointing at a cont-… purchase document, and that the new ids are returned. The only missing behavior is any bound on how many records a single call accepts.

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?

Five dense sentences, each carrying distinct operational information — preference, transactionid inheritance, document-payment special case, atomicity, and the salestax exclusion — with the primary use case front-loaded and 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?

With no output schema the description correctly closes the loop by stating it returns the new ids, and it covers atomicity and the notable id-overloading cases. What remains unstated is any batch-size limit or what happens when an array is empty, which matters for a tool whose whole premise is 'many'.

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?

Top-level schema coverage is 0% (income, expenses and transactionid have no schema descriptions), though the nested item properties are documented in detail. The description compensates for the most important gap by explaining that the top-level transactionid is inherited by every record unless a per-item value overrides it, but it never explains the shape or per-entry requirements of the income and expenses arrays themselves.

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 with scope ('Create many income and expense records in one transaction') and immediately distinguishes itself from the one-at-a-time siblings save_income and save_expense. An agent can decide between bulk and single-record creation without opening any schema.

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

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

Explicitly says to prefer this over repeated save_income / save_expense calls, and names the one case where it must NOT be used ('per-item salestax is not supported (use save_expense)'), routing the agent to the correct alternative with the selecting condition.

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 indicate non-read-only, non-destructive; they don't explain side effects. The description fails to disclose that passing an id updates an existing tag, instead implying updates should go through update_tag. This hides actual behavior.

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

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

The description is two sentences and tightly packed: it defines the resource, states the primary use case, and differentiates from update_tag, delete_tag, and set_business_tag without extraneous words.

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

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

The description covers when to use the tool and distinguishes it from similar tools, but it omits the id-based update capability, leaving the tool's full behavior ambiguous and potentially causing an agent to misroute updates.

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 has a clear description. However, the description adds no extra parameter guidance and its create-only framing conflicts with the id parameter's update semantics, limiting the value it adds.

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

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

The first sentence clearly states 'Create a tag,' but the id parameter description says 'Present → update that tag; omit → create a new one,' which contradicts the stated create-only purpose and the explicit guidance to use update_tag for existing tags.

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 conditions: use for new labels, use update_tag for renames/recollors, delete_tag for removal, and set_business_tag for business segmentation. However, the schema's id-based update behavior makes the 'use update_tag' guidance misleading because create_tag also supports updates.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes well beyond that. It discloses the balance side effects of each decision (recording vs returning days), the payslip-overlap refusal with the force override, and explicitly scopes the mutation to leave balances with no ledger posting.

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

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

Front-loaded with the core action and reasonably tight; each sentence conveys a distinct behavioral fact. Slightly dense at five clauses, but nothing is filler.

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

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

With no output schema, the description usefully describes the return (finalised payslips overlapping the period) and the mutation's scope. The only real gap is the undocumented approveddate parameter, so the agent has enough 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 0%, so the description must carry parameter meaning. It explains id, the three decision values, and the role of force, but approveddate is never mentioned, leaving one of four parameters undocumented in both schema and description.

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

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

States a specific verb set (approve, decline, cancel) and resource (a leave request) keyed by id, and clearly distinguishes this decision tool from the creation/list siblings like save_leave_request and list_leave_requests.

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?

Explains the operational conditions well – approving over a finalised payslip is refused unless force is true – which tells the agent when force is needed. It does not, however, explicitly route against a sibling tool or state when NOT to use this versus save_leave_request, so it stops short of full alternative guidance.

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

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

Goes well beyond the destructive/idempotent annotations by disclosing the partial-success contract (skipped ids listed in errors, `error` true only when nothing deleted), the orphan-protection refusal, and the soft-delete/restorable semantics. This is exactly the behavioral context an agent needs before calling a destructive 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?

Front-loads the core action and the soft-delete qualifier, then layers parameter routing, return shapes, and the force caveat. Dense but each sentence carries distinct information; only the return-shape enumeration is slightly heavy for a description.

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

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

No output schema exists, yet the description documents both return shapes ({error} vs {error, deleted, errors}) and the partial-success semantics, plus the link-refusal rule. Nothing an agent needs to invoke this destructive 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 description coverage is 100%, so `id`, `ids` (max 1000, partial success), and `force` are already documented in the schema. The description largely restates those semantics and adds return-shape detail rather than new parameter meaning, so baseline 3 applies.

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

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

States a specific verb+resource ('Delete one customer or many') and immediately qualifies scope with 'to the bin (soft-delete, restorable)'. This clearly distinguishes it from hard-delete siblings like delete_document or delete_supplier and from update_client.

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

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

Explicitly routes by parameter: send `id` for one customer, `ids` for many. States the default refusal behavior for linked documents, the `force:true` escape hatch, and names the alternative 'archive via update_client'. When-to-use and when-to-override are both covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known without the description. The description adds one genuinely new behavioral fact — the Overview dashboard is protected and will fail — but says nothing about recoverability (restore_deleted exists as a sibling) or required permissions.

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

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

Two short sentences with zero filler, and the protected-Overview constraint is stated immediately after the core action so the agent reads the exclusion before calling.

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 destructive tool with full annotation coverage and no output schema, the description is roughly adequate: action, scope and the Overview exclusion are all present. The missing pieces — how to identify a dashboard id and whether deletion is reversible — are the ones an agent would most need.

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

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

Schema description coverage is 0% for the single required parameter 'id', so the schema gives the agent no meaning at all. The description does not explain that this is a dashboard identifier or where to obtain one (list_dashboards, get_dashboard), leaving the only parameter undocumented in both places.

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 ('Delete a custom dashboard') and narrows scope with 'custom', which separates it from read/update siblings like get_dashboard and update_dashboard. It stops short of naming a sibling alternative, so it is clear but not fully differentiated.

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 clause 'The Overview can't be deleted' gives one concrete when-not condition, which is useful guardrail guidance. However, it never says when this tool should be chosen over alternatives (e.g. hiding vs deleting, or that restore_deleted can undo it), so usage is only partially 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 say destructiveHint=true and idempotentHint=true, which would lead an agent to assume hard, irreversible deletion. The description corrects this by disclosing that the operation is reversible, that the document AND the payments settling it are moved to the bin together, and that list_binned/restore_deleted are the recovery tools. This is substantial behavior disclosure beyond the structured fields.

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

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

Three sentences, each earning its place: what it deletes, what happens on deletion/recovery, and how to source the id. The core action is front-loaded in the first clause.

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

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

For a single-parameter mutation with no output schema, the description covers the affected entity, side effects (payments moved too), reversibility, recovery tooling, and id sourcing. Nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter (id) with 0% schema description coverage, so the description must carry the load — and it does, explaining that the id identifies a document and how to obtain it via list_documents by number or contact. It adds real meaning, though it doesn't specify id format (UUID vs numeric).

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 (delete) and resource (document), enumerates the document types covered (invoice, quote, credit note, debit note, bill), and scopes it to deletion by id. An agent can immediately distinguish it from delete_document_line, delete_expense, or delete_journal_entry.

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

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

Gives a concrete workflow instruction ('Find the id yourself with list_documents (query by number or contact); never ask the user for an id') and points to the recovery path (list_binned, restore_deleted). It does not, however, state when not to use this tool — e.g. when only a single line should be removed via delete_document_line instead.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true; the description aligns with them and adds useful context by requiring the parent document id to update the right document. It doesn't elaborate on side effects like document totals, but this is acceptable given the annotations.

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

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

Three tight sentences cover the operation, key parameters, and alternative tool. There is no filler or repeated schema content.

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

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

For a destructive tool with annotations covering safety and a fully documented schema, this description covers the necessary call pattern, clarifies the practical requirement, and routes to the correct alternative. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to document every field. It adds value beyond the schema by emphasizing that id is the line id and quinvoice is the parent document id, and by noting quinvoice is required in practice even though it isn't in the schema's required list.

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 action and resource: 'Delete a line item from a document (invoice, quote, bill, etc.)'. This clearly distinguishes it from sibling tools like delete_document and update_document_item.

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 agents when not to use this tool: 'To change a line rather than remove it use update_document_item (or update_document_items_bulk for several)'. It also gives the key call requirement to pass quinvoice so the correct document is updated.

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 flag destructive=true and idempotent=true, and the description adds context annotations cannot carry: deletions are soft and restorable, the ledger recomputes so linked bills and transactions stay consistent, and partial-success semantics are spelled out precisely ('error is true only when nothing was deleted').

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

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

Front-loaded with the delete semantics, then mode selection, then result interpretation, then a safety prompt. Dense but every sentence carries decision-relevant information; 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?

There is no output schema, and the description compensates by documenting both return shapes and how to read partial failure. Confirmation guidance and ledger-consistency behavior round out what an agent needs for a destructive, restorable mutation.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by pairing each parameter with its distinct return shape ({error} for id vs {error, deleted, errors} for ids) and clarifying the skip conditions for ids.

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 and resource ('Delete one expense or many') plus the crucial scope qualifier that this is a soft-delete to the bin and restorable, which distinguishes it from any hard-delete interpretation and from save_expense/list_expenses.

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

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

Explicitly routes between the two call modes ('Send `id` for one expense... Or send `ids` (up to 250)') and adds a procedural guardrail ('Confirm with the user before deleting'). It does not name restore_deleted as the undo path, only implies it with 'restorable', so a sibling pointer is the one missing piece.

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 idempotentHint=true, but the description adds substantial context beyond them: deletion is soft and restorable, batch calls can partially succeed, error is true only when nothing was deleted, and the ledger recomputes so a linked invoice's outstanding balance is restored. That downstream side effect is exactly the kind of behavior an agent needs before invoking a destructive tool.

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

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

The core action and its soft-delete nature are front-loaded in the first clause, then the two modes, then the partial-success semantics, then the safety instruction. There is no filler; even the brace notation is there to convey return shapes that the absent output schema would otherwise leave undocumented.

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

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

With no output schema, the description takes on the burden of documenting return values and does so for both call modes, including the tricky partial-success case. For a destructive two-parameter tool it leaves nothing material for an agent to guess.

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 goes further by tying each parameter to a distinct response shape (`id` returns {error}; `ids` returns {error, deleted, errors}) and by explaining the skip semantics of non-owned, already-deleted, or unknown ids. It adds real meaning beyond the schema's plain field 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 ('Delete one income record or many') and immediately qualifies the operation as a soft-delete 'to the bin (soft-delete, restorable)'. That distinguishes it from a hard delete, though it never explicitly names adjacent siblings such as unlink_income_transaction or delete_expense, leaving the agent to infer the boundary.

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

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

It clearly routes between the two modes: send `id` for a single record or `ids` for a batch of up to 250 in one call. It also adds a procedural guardrail, 'Confirm with the user before deleting,' but gives no explicit when-not guidance (e.g., use unlink_income_transaction when you only want to detach a bank transaction).

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

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

Discloses irreversibility ('Immediate and irreversible') and the limitation on auto-generated entries, which complements the destructiveHint annotation. The instruction to confirm with the user adds practical behavioral context beyond the annotations.

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

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

The description is concise yet complete, with each sentence adding essential information: action, irreversibility, scope, alternative method, and confirmation requirement. No redundant content.

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

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

Given the simple single-parameter interface, the description fully covers the operation, its side effects, and the correct usage context. No output schema exists, so no return value description is needed.

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 'id' parameter is described generically in the schema, but the tool description enriches it by explaining the id format 'ent...' for manual entries and contrasting with 'ent-1-inv...' type ids. This gives the agent a clear understanding of what value to pass.

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 action ('Permanently delete') and the target ('MANUAL journal entry by id'), distinguishing from siblings like delete_document or delete_expense. The scope is explicit and unambiguous.

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

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

Provides explicit guidance on when to use (manual entries only) and when not to use (auto-generated entries, delete the source document instead). Also instructs to confirm with the user, covering the decision-making process.

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 beyond the destructiveHint annotation by explaining that deletion affects every user of the business, acts as a retraction rather than a read state, and is irreversible. This fully discloses the behavioral impact.

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

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

The description is concise, well-structured, and front-loaded with the core action. Each sentence adds useful information without unnecessary verbosity.

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

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

The description provides sufficient context for safe and correct usage, including the tool's scope, irreversibility, user impact, and distinction from a related non-destructive operation. No critical contextual 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, id, is already described in the schema as 'Id of the message.' The description adds no additional semantic detail beyond restating that deletion is by id, so it does not improve on the 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 action (permanently delete), the resource (in-app message/notification), and the identifier (by id). It also distinguishes the tool from mark_message_read, 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?

The description explicitly contrasts this tool with mark_message_read and warns that deletion is immediate and irreversible, advising confirmation with the user. This gives clear guidance on when to use it and what caution to apply.

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 idempotentHint=true, so the safety profile is covered; the description goes well beyond them by disclosing side effects that annotations cannot express — journal entries leaving the books, the pay-date action being switched off, the no-op preview behavior with reason 'confirm-required', and the locked-period refusal. This is exactly the extra context the bar asks for.

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, all load-bearing, with the destructive effect front-loaded and the confirm protocol second. Slightly dense phrasing ('answers reason confirm-required') but nothing is wasted.

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

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

No output schema exists, yet the description still tells the agent what the unconfirmed call returns (a reason and a preview of what would be removed) and what failure mode to expect. For a destructive two-parameter tool this is complete enough to drive correct invocation.

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

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

Schema coverage is only 50% (id is undocumented), so the description must compensate, and it does for confirm: it explains the preview-then-confirm contract and that confirm true must only be sent after user agreement. The id parameter is left implicit but is unambiguous given the tool name.

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 ('Move a pay run and its payslips to the bin') and immediately clarifies this is a reversible soft delete rather than a hard removal, which distinguishes it from the sibling delete_payslips. An agent can tell exactly what the call does without opening the schema.

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

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

Gives an explicit two-step protocol: call without confirm to preview, ask the user, then call with confirm true — plus the refusal condition for locked periods. It never names the nearest alternatives (delete_payslips, restore_deleted) as a routing hint, 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?

Goes well beyond the annotations: the journal leaving the books with a finalised payslip, the two-phase confirm protocol, the confirm-required reason response, the refusal conditions, and the whole-batch refusal for missing or foreign ids. This is exactly the destructive-side-effect context an agent needs before committing.

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

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

Front-loaded with the verb and action, and every sentence carries operational information (journal behavior, confirm workflow, refusal rules, batch semantics). The terse telegraphese is dense but not padded, though the phrasing takes a moment to parse.

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

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

With no output schema, the description supplies the relevant response behavior (confirm-required reason with the would-be deletions) and all edge-case outcomes for a destructive mutation tool. Nothing an agent needs to call this correctly appears 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 only 50% (ids is undocumented in the schema), so the description must compensate. It does: ids is clarified as batch identifiers where a missing or another business's id refuses the whole batch, and confirm's role is detailed with the resulting behavior, adding meaning beyond the schema's one-line hint.

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

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

States a specific verb+resource (delete payslips) with scope (by id, batch), clearly distinguishing it from sibling finalise_payslips and delete_payrun. An agent knows exactly what this does without opening the schema.

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

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

Gives explicit procedural guidance: without confirm true nothing changes and the reason confirm-required is returned, so ask the user then call again with confirm true. It also lists when the call is refused (locked period, self-finalising pay run). It lacks explicit cross-references to alternative sibling tools, keeping it at 4.

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

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

Annotations already cover destructiveness and idempotency, and the description still adds substantial context beyond them: soft-delete is restorable, bulk runs in one transaction, partial success semantics (unowned/already-deleted ids skipped into errors), that `error` is true only when nothing was deleted, and that document lines retain their own name/price copies.

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 front-loaded with the decision-relevant fact (restorability, then the id-vs-ids branch, then partial-success semantics). No filler or restatement of the name/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?

With no output schema, the description carries the entire return-contract burden and does so precisely for both modes, including the counterintuitive 'error is true only when nothing was deleted' rule and document-line snapshot behavior. Nothing an agent needs to invoke or interpret the call is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: it ties each parameter to a distinct return contract (`id` → {error}; `ids` → {error, deleted, errors}) and explains the partial-success behavior of `ids`. It stops short of the factual limits the schema already carries (maxItems 1000).

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 ('Delete') and resource ('product'), plus scope (one or many) and the nature of the delete ('soft-delete, restorable'). This distinguishes it from hard-delete siblings like delete_document and from restore_deleted (the inverse operation).

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

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

Explicitly routes the caller: 'Send `id` for one product... Or send `ids` (up to 1000) to delete many in one transaction.' That is clear usage context, but it never names a sibling alternative or states exclusions (e.g., when to prefer per-item delete over bulk, or that restore_deleted undoes this).

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 flag destructive/idempotent/not-readOnly, and the description adds substantial context beyond them: it is a soft-delete to the bin (restorable), partial success is possible in bulk mode, error is true only when nothing was deleted, and linked bills/expenses block deletion unless forced. This is exactly the behavioral detail the annotations cannot convey.

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

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

Front-loaded with the core action (soft-delete, restorable) and mode selection, and every sentence carries information. It is dense—packing return shapes and partial-success semantics into a paragraph—which slightly hurts scannability but leaves 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?

No output schema exists, and the description compensates fully by documenting the return shapes for both modes and the meaning of the error fields. For a destructive bulk tool, the refusal/force/link behavior is completely covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the `id`/`ids` return shapes, the 1000 cap in transactional context, the partial-success error listing, and the PROD-663 rationale for `force`.

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+resource and immediately distinguishes the two modes (single `id` vs bulk `ids`). It also names the sibling alternative (save_supplier) for the archive case, so an agent can route correctly without opening schemas.

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

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

Explicit when-to-use guidance: send `id` for one, `ids` for many, use `force:true` to override the linked-expense refusal, or archive via save_supplier instead. Conditions and alternatives are spelled out rather than 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 already declare this as destructive, idempotent, and not read-only, but the description adds crucial behavior beyond that: the tag moves to the bin rather than being permanently lost, and it can be restored. It also surfaces the confirmation and archiving alternatives, which are valuable behavioral details for a destructive operation.

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

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

Three short sentences, with the core action and recovery behavior front-loaded. Every sentence adds useful information: what it does, how to recover, and safer alternatives.

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

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

For a simple one-parameter destructive tool with no output schema, the description covers the essential context: lookup by id, bin-based recovery, an archiving alternative, and user confirmation. Nothing critical is missing for correct invocation.

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

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

The schema has only one parameter, 'id', with 0% description coverage, and the description adds only that deletion is 'by id'. It does not specify the id format or where to obtain it, though the single obvious required parameter keeps the gap small.

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 ('Delete a tag') and adds the key lookup field ('by id'). This clearly distinguishes it from siblings like update_tag, list_tags, and restore_deleted.

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 recommends archiving via update_tag first and asks the agent to confirm with the user before deleting. It also names the recovery path through list_binned and restore_deleted, so the agent knows both alternatives and consequences.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: the delete is a soft delete ('moves to the bin') recoverable via restore_deleted, and it stays scoped to the same product. It doesn't discuss cascading effects (line items, documents referencing the variant), which keeps it from a 5.

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

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

Two tight sentences, action and recovery semantics front-loaded, alternatives trailing. No wasted clauses.

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

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

For a two-parameter, no-output-schema mutation, the agent knows what happens to the entity, that it's recoverable, and what tools to use instead. Missing only the side effects on related records, which is minor here.

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

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

Schema coverage is 100% with both parameters described, so baseline is 3. The description mentions 'by id' and implies the parent product context, but doesn't resolve the schema's odd signal where id is described as 'Required in practice' yet absent from the required array — that ambiguity is left to 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?

States a specific verb and resource ('Delete a product variant by id') and immediately distinguishes itself from two siblings by naming restore_deleted and save_variant. An agent can route correctly without inspecting the schema.

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

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

Explicitly covers the alternatives: restore_deleted for recovery and save_variant for create/edit. Both the when-to-use-this and the when-to-use-something-else cases are stated.

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?

readOnlyHint already covers the safety profile, and the description adds real behavioral value beyond it: tiles the plan or data cannot answer return as 'unavailable' rather than 0, which prevents an agent from misreading a missing metric as zero. It also discloses that a comparison period is included in the response, which matters given there is no output schema. It stops short of explaining how the comparison period is derived.

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

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

Two short sentences, front-loaded with the core result and followed immediately by the most surprising behavior (unavailable, never 0). Nothing is padding.

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

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

For a read-only tool with no output schema, the description covers the essential contract: what comes back (per-tile figures plus prior-period comparison) and how failures are represented. The remaining gap is the 'id' parameter and whether the comparison period mirrors the requested span.

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 67%: periodStart and periodEnd are documented in the schema with format and meaning, but 'id' has no description at all. The description refers to 'a period' without clarifying inclusion semantics or that the comparison window is derived from the supplied period, so it adds little beyond the schema.

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

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

The description gives a specific verb-less but concrete outcome: every tile's figure for a period plus the prior period for comparison. That distinguishes it from get_dashboard (definition) and update_dashboard (mutation) well enough to choose it, though it never explicitly says it operates on the dashboard identified by 'id'.

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?

There is no explicit when-to-use or when-not-to-use guidance and no sibling is named, despite close siblings like get_dashboard, evaluate_report, and evaluate_report_batch. Usage is only inferable from the fact that figures for a period are returned.

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 genuinely useful behavior beyond that: with snapshotid the period evaluates FROZEN from the filed listing and the numbers are immutable, without it the evaluation is LIVE against current books. That frozen/live distinction is exactly the kind of consequence an agent needs before calling. It stops short of describing the response envelope or any size/performance characteristics of a large evaluation.

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 contract — resolve a template or a view against a period — is front-loaded in the first clause, and the frozen-vs-live distinction is placed last where it reads as the key caveat. The view enumeration with an ellipsis plus the parenthetical examples is somewhat redundant given it also points the reader to the `view` param for the full list. Dense but nearly every clause carries information.

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

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

For a 20-parameter tool with no output schema, the description covers the decisions that matter most: which mode, which naming scheme, and whether the result is live or frozen. Given 90% schema coverage, the remaining gaps are mostly about return shape — only payables/receivables get a hint of output, and nothing tells the agent what a template evaluation returns. Adequate and well beyond minimum viable, but not fully self-sufficient.

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

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

Schema description coverage is 90%, so the schema already documents the 20 parameters thoroughly, and most of the description's parameter talk (source format, templateid, snapshotid) echoes what the schema says. The one thing the description adds is a concrete illustration of what a view such as payables returns (supplier, amount, due date, currency), which is output context rather than parameter meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource — "Resolve a report template OR an insight view against a period" — and immediately explains the two modes (templates measured off the ledger, views data-driven). This is far clearer than the title's bare restatement. It does not, however, distinguish itself from sibling tools like evaluate_report_batch, evaluate_report_session or open_report_session, so an agent still has to infer when this single-report tool is the right entry point.

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?

Strong internal routing guidance: templates are named via `source` or `templateid`, views via `view`, and the reader is told what each mode produces. The snapshotid paragraph clearly frames the frozen-vs-live decision, which is the main usage fork. What's missing is any exclusion relative to the sibling evaluation tools, so the agent gets no help choosing this tool over the batch/session variants.

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 that the tool requires an open session, that errors are returned inline per slot, and that it leverages a single session dataset build to reduce round trips. These are important behavioral details not present in the annotations.

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

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

The description is concise and well-structured, starting with the core capability, then parameter details, then usage guidance. It avoids unnecessary filler and communicates everything needed in a compact format.

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 all necessary context: the batching capability, the parameter structure, the response behavior (what each results slot contains), the session prerequisite, and alternatives for single or one-off evaluations. Despite lacking an output schema, the description sufficiently explains the expected result format, making the tool fully usable.

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

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

The description elaborates on the 'requests' parameter, specifying the structure of each item: '{view|source|templateid, periodStart?, periodEnd, ...}'. This adds crucial semantic information that the schema alone (which only says 'items: type object') does not provide, making the parameter fully understandable.

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

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

The description clearly states that the tool evaluates up to 24 report templates/views in a single round trip, using specific terms like 'evaluate', 'templates/views', and 'session dataset build'. It also distinguishes itself from sibling tools by mentioning the batch nature and session requirement.

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 provides when to use this tool versus alternatives: 'for a single view use evaluate_report_session, or evaluate_report for a one-off outside any session.' It also states the prerequisite 'Requires an open session (open_report_session first)', giving clear guidance on usage conditions.

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?

readOnlyHint already marks it non-mutating, but the description adds substantive behavior: cached dataset, tens-of-milliseconds latency, identical answers to /report/evaluate, and live-only scope. It does not explain session invalidation or error behavior, so it is not complete.

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 opens with the primary evaluate action, then the latency/cache benefit, then the interactive and live-only constraints. Every sentence adds decision-relevant information.

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

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

For a 19-parameter session-cached tool, the description covers the key operating constraints (live-only, frozen-period fallback, interactive use) and names the equivalent /report/evaluate behavior. It omits the session-creation prerequisite and any return-shape detail, but the core invocation context 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 coverage is 79%, so the schema is already the primary source for most of the 19 parameters. The description only adds that view is the full list and that source/templateid are alternatives, leaving constants, version, and other params to the schema.

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

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

The description gives a specific verb and resource ('Evaluate a template ... or an insight view') and names both accepted selectors, source/templateid and view. It also distinguishes the tool from the full /report/evaluate pipeline by its cached-session, low-latency behavior.

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

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

It states the interactive scenarios (period slides, template/view switches, constant tweaks) and an explicit exclusion: live books only, with frozen periods routed to /report/evaluate with snapshotid. It stops short of naming open_report_session as a prerequisite or addressing evaluate_report_batch, so the routing is not fully exhaustive.

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

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

Beyond the readOnlyHint annotation, it discloses non-obvious behavior: every call creates a duplicate file, the artifact is retained rather than imported into the books, and a missing or cross-business id fails with reason document-not-found. It also states what the call returns (the new file's id and name), which annotations do not cover.

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

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

Purpose is front-loaded in the first clause, followed by return handling, duplication warning, retention semantics, and error behavior in that order. Every sentence carries a distinct, actionable fact 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?

With no output schema and a single-parameter input, the description carries the remaining burden and does so: it names the returned fields, explains how to surface the file to the user, warns about duplicate artifacts, and specifies the failure mode. Nothing needed to invoke it correctly is missing.

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

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

There is only one parameter and the schema coverage is 100%, with the schema already naming the accepted document sources (list_invoices, get_document). The description restates that the id can be an invoice, quote, credit note or other document and adds the cross-business rejection rule, but adds little beyond the schema. A 3 baseline 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 gives a specific verb and resource (save a document as a PDF in the business's Files) and scopes what counts as a document (invoice, quote, credit note or any other kind), plus the rendering rule 'drawn as the customer sees it'. This clearly separates it from siblings like list_files, attach_file, remove_file, and save_document.

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

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

It states the operating condition ('each call saves a new copy, so call it once per request') and tells the agent what to do with the result (cite it as a file tag so the user can open and download it). It lacks an explicit comparison to alternatives such as list_files or send_document, so the agent must infer when another sibling is the better 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?

Goes well beyond the destructiveHint annotation by disclosing the dry-run/refusal contract ('answers reason confirm-required with what it would post'), the invariants that will refuse a call (locked period, self-finalising pay run), and batch atomicity ('A missing or another business's id refuses the whole batch'). This is exactly the behavioural context needed for a mutating, journal-posting operation.

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?

Five sentences, front-loaded with the effect and then the confirm protocol, with no filler. It is dense — the refusal conditions are packed into single clauses — but each sentence carries distinct operational information.

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

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

For a two-parameter destructive mutation with no output schema, the description covers effect, side effects avoided, confirmation flow, refusal conditions, and atomicity. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is only 50% (ids is undocumented), and the description compensates by defining batch semantics for ids — all-or-nothing refusal on missing or cross-business ids — and by adding the confirm-required response contract beyond the schema's one-line note. It still doesn't state what an id is (payslip id) or whether duplicates/ordering matter.

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 ('Finalise payslips by id') plus the concrete consequence ('each posts its journal to the books'), which distinguishes it from save_payslip (drafting) and delete_payslips in the sibling list. An agent can tell what changes in the domain without opening the schema.

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

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

Gives an explicit two-step protocol ('ask the user, then call again with confirm true') and scope exclusions ('Sends no email and files no returns'), so the agent knows this is not the tool that distributes pay slips. It doesn't compare against save_payslip/populate_payrun explicitly, so it falls 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?

Far exceeds the readOnlyHint annotation: it discloses the ±7 day window, 3% FX tolerance, confidence >= 0.9 threshold, requires_confirmation flag for cross-currency matches, and the exact shape of the proposal/adjusting line. It also states explicitly what it never does (record a match or adjusting line).

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?

Very dense and front-loaded — the core behavior and window lead, routing guidance follows. It is long and the proposal/currency explanation is somewhat repetitive, but nearly every sentence carries operational information rather than filler.

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

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

There is no output schema, so the description carries the return-value burden itself and does so fully: it enumerates the returned fields, the candidates/best structure, and confidence semantics. Combined with the routing guidance, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and fully documents the single documentid parameter (cont-… or inv-…). The description only restates the same id format, adding no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('surface the candidate bank transactions') scoped precisely to an OUTSTANDING or OVERDUE invoice or bill. An agent can distinguish it from settle_bills, record_document_payment, and match_transactions without opening any schema.

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

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

Gives explicit when-to-use ('Run this whenever you report an overdue/outstanding invoice or bill'), names alternatives (settle_bills, save_income, record_document_payment) and the exact conditions that select each. It even supplies a decision branch (check list_transactions for $incomeids first).

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, but the description goes far beyond: it states matches are suggested and never recorded, discloses the limit cap (default 50, hard max 200) and the truncated/matched semantics when more rows match, and spells out the double-counting hazard of record_document_payment. This is rich behavioral context an agent genuinely needs.

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 front-loaded and dense: the bulk purpose, selection modes, cap behavior, return shape, and settlement routing each earn their place. The settlement-routing sentences at the end are arguably tangential to *this* tool, but they prevent a costly double-payment mistake, so the length is justified rather than padded.

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

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

Despite having no output schema, the description documents the return shape (results/document/candidates/best, count, matched, truncated, limit), the caps, and the null-vs-partial behavior. For a read-only, 10-param, no-required-param tool, 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the either/or semantics (filter fields are ignored when documentids is passed), the combination logic for filters, and the paging behavior tied to limit/truncated. It does not restate every param, but the additive value is clear.

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 (find/return candidates) and resource (transactions for documents), and immediately frames itself as the 'BULK / multi-document version of find_candidate_transactions', distinguishing it from its closest sibling. An agent can tell exactly what it gets back (each document + candidates + best match) without opening a schema.

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

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

Explicit when-to-use ('reconciling a large AP/AR backlog needs one call, not one round-trip per bill'), the two selection modes, and a concrete filter example (type=bill + unpaid + status=overdue). It also routes away to alternatives: settle_bills for settling, save_income vs record_document_payment depending on whether a bank line already has income, and list_transactions to check $incomeids.

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

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

Discloses non-obvious behavior annotations cannot: duplicates and below-threshold items are skipped, the owner is notified exactly once, and crucially a second run over the same period re-flags but suppresses a repeat notification. This idempotent-notification semantics is exactly the context an agent needs before re-running.

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

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

Two dense sentences, front-loaded with the core action and period default. The second sentence on repeat-run behavior is slightly awkward but earns its place by covering an important edge case.

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

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

For a write tool with no annotations beyond safety hints and no output schema, the description covers action, scope, threshold, notification, and re-run semantics well. It omits what the returned result or 'flag' state looks like, a minor gap.

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

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

Schema coverage is 100% with clear per-parameter descriptions (date defaults, threshold with R5,000 preset). The description reinforces threshold/duplicate behavior but adds no syntax or format detail beyond the schema, so baseline 3 is correct.

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 (flag) and resource (expenses with no slip/receipt attached), plus scope (a period). No sibling tool overlaps this action, so an agent can identify it immediately from name and description.

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

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

Usage is implied by the purpose (chase expenses missing receipts) and the description gives a sensible default period, but it never states when to prefer this over another approach or any preconditions. Adequate but no explicit guidance or exclusions.

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

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

Annotations only declare readOnlyHint=true; the description adds real interpretive context beyond that: under 'sponsored' the business is not metered so limit/left/out are not a real cap, under 'trial' there is no paid plan yet, and 'legacy'/'plan-label' change how the allowance should be read. It does not discuss freshness/latency or auth, but the disclosed caveats meaningfully shape how the returned numbers must be interpreted.

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

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

Front-loaded with the subject ('this billing period's action usage') and densely information-bearing, with no filler sentences. The structure is a near-run-on enumeration of fields and flags that is hard to scan, costing it a point despite the absence of waste.

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

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

With no output schema, the description correctly carries the return-value burden and explains each notable field and its caveats, so an agent can interpret the response without external docs. It could be slightly more complete on cadence (e.g. whether values are real-time vs. end-of-day), but for a parameterless read tool it is largely self-sufficient.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing parameter-side for the schema to cover. The description instead spends its budget on return-field semantics, which is the right use here, though that belongs to contextual completeness rather than parameter documentation.

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

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

States a specific verb+resource ('this billing period's action usage') and enumerates exactly what the payload contains (used vs allowance, reset time, prepaid balance, spend/out status, usage by kind, hours saved). It also names the sibling get_subscription as the route for Stripe billing line items, so an agent can distinguish the two without opening a schema.

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

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

Gives one explicit routing rule ('for the plan's Stripe billing line items use get_subscription'), which is genuine when-not guidance. It does not, however, frame the broader context of when an agent should reach for this tool versus other account-level tools like get_business_overview or get_financial_summary.

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 beyond the readOnlyHint annotation by explicitly stating the tool does not pull transactions, does not make live external calls for bankfeeds, and returns an explanatory message rather than an error when no bank connection exists. This fully sets expectations for side effects and error behavior, making the tool's behavior transparent.

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

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

The description is a single detailed sentence but includes some redundancy (e.g., listing providers and bankfeeds twice with similar wording). It is not overly long, but the repetition of 'bank feed' variants could be trimmed. Overall, it is clear and front-loaded with the core purpose, but slightly redundant in the specifics.

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

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

With no parameters and no output schema provided, the description must convey all necessary context. It does so thoroughly: it names the two return fields, explains their sources (live vs. derived), clarifies the no-transaction/no-live-call behavior, and explicitly states the edge-case outcome (message, not error) when no bank connection exists. This is fully complete for an agent to know 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?

There are zero parameters, matching the empty schema with full coverage. The description correctly implies no input is required by explaining what the tool returns with no configuration. Since there are no parameters to document, the baseline of 4 is exceeded by the clear statement that no input is needed and that the tool operates on the business's existing profile.

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 reports the business's bank-connection profile and explicitly excludes pulling transactions. It specifies the two return categories (providers and bankfeeds) and their distinct characteristics, making the tool's purpose unambiguous. The name 'get_bank_profile_status' is descriptive and the description reinforces its role as a status-only reporter.

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

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

The description provides useful guidance by indicating no transactions are pulled and that bankfeeds are derived from stored state with no live external call. This hints at when to use the tool (e.g., for a lightweight status check). However, it does not explicitly compare to sibling tools like refresh_business_data or other getters, so it's slightly less explicit than ideal.

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, covering the safety profile. The description adds useful behavioral context by revealing that this is a bundling call rather than a distinct data source, but it does not describe response shape, pagination, or any aggregation caveats. The added value is moderate but not extensive.

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

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

Two concise sentences with no filler. The core bundling behavior is front-loaded, and the alternative usage is stated efficiently in the second sentence.

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 zero-parameter read-only composite tool, the description sufficiently captures what the call returns and when to use it. The absence of an output schema means a bit more detail about the financial summary or usage context could be helpful, but the current level is adequate 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?

The tool has zero parameters and the schema is empty, so there is no parameter semantics gap to fill. The description accurately reflects the no-input nature; no additional parameter explanation 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 clearly states the tool returns a composite overview: profile + financial summary + feature/usage context. It also explicitly names the two sibling tools it bundles, so an agent can immediately distinguish it from get_business_profile and get_financial_summary.

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

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

The description gives explicit guidance: call this tool when you need the combined overview, and call the individual sibling tools when only one part is needed. This directly answers the when-to-use-versus-alternatives question.

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?

readOnlyHint=true already establishes the safe-read profile, and the description is consistent with it. It adds genuine behavioral context by scoping what is and is not returned (profile fields yes, financials no), which is the key decision input. It stops short of describing freshness/caching of the profile data, so it is not exhaustive.

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

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

Two sentences, front-loaded with the resource and its contents, followed by the disambiguation. The field enumeration is long but earns its place because there is no output schema to carry that information; it is dense rather than padded.

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

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

With no output schema in the definition, the description carries the burden of telling the agent what comes back, and it does so field-by-field, plus states the exclusion and the two alternatives. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for this case is 4. Nothing misleading is said about inputs, and the description correctly implies no arguments are 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?

States a specific resource (the business's own profile) and enumerates the exact fields returned, which is the operative content for a zero-param getter. The second sentence names the two sibling tools it is not, so an agent can distinguish it from get_financial_summary and get_business_overview without opening either schema.

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

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

Explicit routing: financials are excluded, use get_financial_summary for those, or get_business_overview for profile plus financials in one call. Both the when-not and the two alternatives are named with the condition that selects each.

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, so the description usefully adds that tiles are returned inline and that a preset Overview comes back with resolved: true and business-specific tiles. That is genuine behavioral context beyond the annotation, though the second sentence is compressed enough that an agent may not parse the resolved flag's meaning confidently.

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

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

Two short sentences with the read behavior front-loaded and no filler. The trailing clause about the Overview preset is dense but still earns its place by disclosing resolution behavior.

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

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

There is no output schema, and the description covers the shape loosely (dashboard plus tiles, plus the resolved flag). It leaves out where to get a valid id and whether tile content is returned raw or evaluated — relevant given the many dashboard-tile siblings.

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

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

Schema description coverage is 0% and the single id parameter has no description, only min/max length. The description implies the id identifies a dashboard, but it does not say whether it is an id, a slug, or a name, nor how to obtain one.

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?

"Read one dashboard with its tiles" gives a specific verb and resource, and the singular "one" distinguishes it from list_dashboards. It does not explicitly name evaluate_dashboard or get_business_overview as alternatives, so sibling differentiation is only implicit.

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

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

Usage is implied by "Read one dashboard" plus the required id, but there is no explicit statement of when to pick this over list_dashboards or evaluate_dashboard. A single clause like "use evaluate_dashboard to render values" would have lifted this.

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; the description adds genuine context beyond that, notably scope ("any document id this business owns") and a data-interpretation pitfall: a document's totals are header $total/$vat, while $linetotal is pre-VAT and pre-discount, so lines must not be summed to quote totals. It doesn't cover failure behavior for unknown or unauthorized ids, keeping it short of a 5.

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

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

Front-loaded with the core action and return contents, then usage routing, then total semantics. Every sentence carries information, though the final sentence is dense and slightly overpacked with accounting caveats.

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

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

No output schema exists, so the description does the work of describing the return shape (totals, status, lines, contact, money direction) and the meaning of the monetary fields. What's missing is only edge-case behavior for invalid or foreign-owned ids.

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

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

With one required parameter and 100% schema coverage, baseline is 3; the description earns an extra point by defining what counts as a valid id (invoice, quote, credit-note ids returned by list_documents and list_invoices), which the schema's bare "Document id." 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?

States a specific verb and resource ("Get one document by id") and enumerates what comes back: totals, status, line items, contact, money direction. It also distinguishes itself from list_documents/list_invoices by naming them as sources of ids, so an agent can tell the retrieval tool from the list tools without opening schemas.

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

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

Gives explicit operating instructions: find the id yourself via list_documents (query by number or contact) and never ask the user for an id. It also clarifies that invoice, quote and credit-note ids from list_documents and list_invoices are all valid inputs, which removes the main ambiguity in choosing this tool.

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

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

The annotation readOnlyHint=true and the verb 'get' make the read-only nature clear. The description also discloses that it returns failure reasons when applicable, providing transparency about the kind of data returned without suggesting 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 a single focused sentence that front-loads the purpose and lists the returned fields without unnecessary detail. It is concise and well structured.

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

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

With no output schema present, the description compensates by enumerating the key output fields (subject, recipients, time sent, time received, and failure reason). This gives an agent sufficient context to know what to expect from the call.

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

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

The schema already fully describes the single id parameter as the identifier of the email history record. The description merely repeats 'by id' and adds no additional semantic detail beyond the schema, so the baseline score applies.

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

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

The description clearly states the action (get one sent email's history record), the lookup method (by id), and the specific fields returned (subject, recipients, time sent, time received, failure reason). This is distinct from list_emails, which lists emails rather than fetching a single history record.

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

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

The description implies usage when a single email history record is needed by id, but it does not explicitly contrast with list_emails or other email-related tools. Guidance is present but only implicit.

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

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

Adds meaningful behavior beyond the readOnlyHint annotation: sensitive fields (ID and tax numbers) are suppressed, and a non-matching id is treated as an error rather than an empty result. This clarifies privacy and failure semantics, though it doesn't cover pagination or exact error format.

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

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

Three tight sentences with no waste, and the core purpose is front-loaded ahead of the field/error caveats.

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 single-record getter with no output schema, the description supplies the return shape (same fields as list_employees) plus privacy and error behavior. Only the exact error/response form is left implicit.

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

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

Schema coverage is 0% and there is one required id parameter, so the description carries the burden. It only restates 'by id' without giving format, type, or lookup expectations, adding marginal value over the bare schema property.

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 (get) and resource (payroll employee) scoped by id, and anchors the return shape by referencing the sibling list_employees. It is immediately clear what the tool returns, though the differentiation from list_employees is about field parity rather than use case.

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

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

Usage is implied by 'one payroll employee by id' and the comparison to list_employees, but there is no explicit when-to-use guidance or named alternative (e.g., use list_employees to enumerate). The agent must infer the single-record vs list routing.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds meaningful behavioral scope: it reports monthly aggregates, specifies included financial categories, and states that profile details are excluded. This goes 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?

Two sentences with no filler: the first sentence front-loads the resource and key contents, and the second provides exclusions and routes to alternatives. Every part 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?

For a parameterless read-only tool with no output schema, the description is complete enough: it says what data is returned, what is intentionally omitted, and which sibling tools cover the omitted data. An agent can select and invoke this tool correctly without needing more context.

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

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

The tool has zero parameters and the schema is empty, so there is no parameter documentation burden. The baseline 4 for parameterless tools applies, and the description appropriately focuses on output scope rather than 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 names a specific resource (financial summary) and a clear verb ('get'), then enumerates the exact contents: per-month earnings, profit, cashflow, expense/income rollups, and inventory movement. It also explicitly differentiates itself from get_business_profile and get_business_overview, so an agent can distinguish it from nearby 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 explicitly states what this tool does not include ('Profile details are not included') and names the alternatives: get_business_profile for profile details and get_business_overview for both in one call. This gives clear when-to-use and when-not-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, so 'Read-only' is largely redundant, but the description adds real behavioral context: the entitlement gate that suppresses non-entitled guides and the fact that the result is a set of steps. It does not describe error behavior for a non-existent or unentitled id, which is the remaining gap.

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

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

Three short sentences, front-loaded with what the tool does, then the read-only note, then the precondition. Nothing is padded or restated.

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 single-parameter read tool with an annotation covering safety and no output schema, the description is nearly complete, and 'steps of a single guide' conveys the return shape. It stops short of saying what a failed lookup yields, a minor omission.

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

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

Schema coverage is 100% and the id property already carries an example and the 'as returned in a list_guides row' note, so the schema does the heavy lifting. The description reinforces the provenance of the id but adds no new syntax or format detail beyond it.

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?

It states a specific verb (Get) and resource (the steps of a single guide) with a clear scope qualifier (by its id). This cleanly distinguishes it from list_guides, which enumerates rather than fetches one guide's steps.

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 to call list_guides first and to only request an id that list_guides returned, and it names the failure mode (an unentitled guide is not returned). The sequencing and exclusions are fully specified.

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 reinforces this with 'Read-only'. Beyond that it adds genuinely useful behavior not present in structured data: the article is returned as plain text, which tells the agent how to consume the result given there is no output schema.

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

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

A single sentence that front-loads the action and resource, then the provenance and output format, with no filler. 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?

For a one-parameter read tool with no output schema, the description covers action, input source, return format, and safety profile. The only minor gap is failure behavior for an invalid or unknown slug.

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 sole parameter's provenance is already documented in the schema ('exactly as returned in a search_help_articles row'). The description echoes this constraint but adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (one help article), keyed by slug, and explicitly distinguishes itself from the sibling search_help_articles, which returns the slug in the first place. An agent can tell this apart from search_help_articles or get_guide without opening a schema.

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

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

Gives clear context for use: read a single article after search_help_articles produced the slug, in order to walk the user through it. It does not state exclusions (e.g. what to do if the slug is stale or not found), so it falls short of a full when/when-not rubric.

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