stub

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 readOnlyHint=false and destructiveHint=false, so the mutation profile is known. The description adds the useful constraint that the parent entry must already EXIST (one line per call), but says nothing about balancing rules, entry status effects, or what happens on failure. With annotations carrying the safety profile, this is adequate but not rich.

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 sentence, front-loaded with what the tool does, followed immediately by the two routing alternatives. 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 line-level mutation whose parameters are fully documented in the schema and whose safety profile is in annotations, the description covers what an agent needs to pick it. It omits behavioral detail about debit/credit balancing and the effect on the parent entry's totals, which is the only notable gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter (including the role sentinel behavior and debit/credit conventions). The description adds no parameter-level detail and only implies the single-line-per-call semantics, 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 ('Add ONE debit or credit line to an EXISTING journal entry') with clear scope. It explicitly differentiates itself from the two adjacent siblings save_journal_entry and update_journal_line, so an agent can route 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?

Names both alternatives by name and gives the exact condition that selects each: whole-entry creation goes to save_journal_entry, modifying an existing line goes to update_journal_line. This is explicit when/when-not guidance with alternatives.

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

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

Annotations already 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 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 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?

Annotations only declare readOnlyHint=false / destructiveHint=false, so the description carries most of the behavioral burden — and it delivers: all-or-nothing atomicity, top-level transactionid scope with per-item override precedence, the cont-… id making an expense a bill payment, and return of new ids. Missing only auth/permission or rate-limit context.

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

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

Four tight sentences, each carrying a distinct behavioral fact (preference, linking precedence, bill-payment semantics, atomicity/limitation/return). Front-loaded with the primary purpose and no filler.

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

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

For a nested-array bulk mutation with no output schema, the description covers atomicity, precedence, a special id semantic, a limitation, and return values. What is absent is minor — e.g. that both arrays are optional and the empty-required-array shape.

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

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

The schema's item-level field descriptions are already extensive, but the description adds real meaning the schema does not: the top-level vs per-item transactionid precedence, and the accountid-equals-purchase-document-id interpretation. The top-level transactionid remains undocumented in the schema, and the description covers 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?

States a specific verb and resource (bulk-create income and expense records in one transaction) and explicitly distinguishes itself from the single-record siblings save_income / save_expense. An agent can identify the tool's role 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 preference rule ('prefer this over repeated save_income / save_expense calls') and a named exclusion with a fallback (per-item salestax is not supported — use save_expense). Both when-to-use and when-not are 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 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 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?

The description goes well beyond the annotations by detailing side effects: permanent and irreversible deletion, no linked-record check, ledger recomputation, and consistency of linked bills/transactions. It also includes the expectation to confirm with the user, which is behavioral guidance. This fully discloses the impact of invoking the tool.

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

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

The description is compact and information-dense, covering purpose, side effects, and usage guidance in three sentences. No redundancy or extraneous details are present. The structure is ideal for an agent to quickly grasp the tool's 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?

For a simple delete operation with one parameter and no output schema, the description provides all necessary context: what it deletes, how it behaves (permanent, recomputes ledger), and the required user confirmation. An agent can safely and correctly invoke this tool based solely on the description, including understanding its impact on linked data.

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 a single required parameter 'id' (string), and the description references 'by id' to indicate what the parameter is. Since the schema already fully covers the parameter definition and the description adds no additional semantic details (e.g., format, source, or validation), the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Permanently delete an expense by id') and distinguishes it from other delete operations by specifying the target resource ('expense'). The scope is unambiguous, and the phrasing immediately tells an agent that this tool removes a single expense 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 instructs the agent to 'Confirm with the user before deleting,' which is a critical usage guideline for a destructive operation. It also notes that no linked-record check is performed and that the ledger recomputes to maintain consistency, informing the agent about when this tool is appropriate (direct deletion without collateral checks). However, it does not explicitly compare against alternative delete tools (e.g., delete_income, delete_journal_entry), leaving some inference to the agent.

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

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

Goes beyond annotations by explaining immediate irreversibility, the absence of a linked-record check, the ledger recomputation, and the restoration of a linked invoice's outstanding amount. Also instructs user confirmation.

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

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

Two dense but readable sentences cover the action, consequences, and required user confirmation without unnecessary 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?

Covers the essential side effects and confirmation requirement. No output schema exists, so the lack of return-value detail is acceptable; error cases are not mentioned but are not critical for this tool.

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

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

The only parameter, id, is referenced as the income record id. Though the schema provides no field description, the tool description makes the parameter's purpose clear enough for a simple identifier.

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 an income record by id. Distinguished from related tools like delete_expense and save_income.

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: irreversible, no linked-record check, ledger recomputes, and confirm with the user. Does not name alternative tools like restore_deleted or unlink_income_transaction, but the usage context is still clear.

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

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

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?

The description explicitly states the deletion is permanent and irreversible, which fully discloses the destructive nature of the operation. This aligns with the destructiveHint annotation and provides clear expectations to the agent.

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 succinct, with no unnecessary words. It conveys all essential information in two sentences, making it easy to parse and understand quickly.

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

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

The description covers the key aspects: what happens (permanent deletion), the scope (everywhere applied), and the safety precaution (confirm with user). It does not mention return values or additional side effects, but for a simple delete operation, this is sufficient. A minor gap is that it doesn't specify what happens if the tag does not exist, but that is not critical.

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 minimally described in the JSON schema (type string) without additional context in the description. Since the schema already covers the existence and type of the parameter, the description adds no extra semantic meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (delete), the resource (tag), and the scope (removed everywhere it is applied). It distinguishes itself from sibling tools like create_tag and update_tag without needing to reference them.

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

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

It explicitly advises confirming with the user before deleting, which is a critical usage guideline for destructive operations. This tells the agent when and how to invoke the tool safely.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description reinforces those with 'Permanently delete' and 'This cannot be undone.' It adds a clear irreversibility warning that aligns with, and slightly extends, the structured annotation information.

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 sentence that front-loads the core action, then adds the permanence warning and the save_variant alternative. Every word earns its place with no redundancy.

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

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

The description covers the main delete semantics and the annotation profile handles safety, but the unresolved id/productid requiredness conflict is left unaddressed. Since there is no output schema, a brief hint about the expected result or confirmation would also improve completeness.

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 no parameter-level meaning beyond saying 'by id.' The schema itself contains an odd 'Required in practice' note for id while productid is the only required property; the description does not resolve this ambiguity.

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

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

The description states the specific verb 'delete', the resource 'product variant', and the identifier ('by id'), and adds 'Permanently' to set expectations. It is clearly distinct from save_variant and other delete_* 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?

It explicitly directs the agent to use save_variant instead when the goal is to create or edit a variant, while framing this tool as the permanent deletion path. This provides an actionable routing rule and a caution about irreversible 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?

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?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them, disclosing the dry-run gate, the confirm-required reason token, batch atomicity ('refuses the whole batch'), and side-effect boundaries (no emails, no returns). No auth/permission detail, but the behavioral profile is unusually rich.

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, then scope negatives, the confirm workflow, and refusal conditions in a logical order with no filler. A couple of clauses are dense and run-on ('Without confirm true it changes nothing and answers reason confirm-required with what it would post'), but every sentence adds actionable 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 2-parameter mutation tool with no output schema and minimal annotations, the description supplies the workflow, prerequisite safety gate, failure modes, and side-effect scope. An agent has everything it needs to call this correctly, including the partial-response hint about `reason: confirm-required`.

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% (only `confirm` is documented in-schema), so the description carries `ids` by explaining its batch semantics and that a missing or another business's id refuses the whole batch. It also reinforces the confirm gate beyond the schema text. It does not specify the id string format, so it falls just short of full compensation.

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

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

States a specific verb+resource (finalise payslips) and the concrete effect ('each posts its journal to the books'), which distinguishes it from siblings like save_payslip, get_payslip, delete_payslips, and populate_payrun. It also scopes what it does NOT do ('Sends no email and files no returns').

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

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

Gives an explicit two-step workflow: without confirm=true nothing changes and the tool answers with what it would post; the agent must ask the user, then re-call with confirm=true. Refusal conditions (locked period, self-finalising pay run, missing/foreign id) tell the agent exactly when the call will fail and why.

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?

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?

The readOnlyHint annotation already establishes that this is a read-only operation. The description adds valuable behavioral context by stating that financials are not included, setting expectations about the response scope beyond what the annotation conveys. It does not contradict the annotations.

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

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

Two concise sentences with no redundancy. The core purpose is front-loaded, and the exclusions and alternatives are stated efficiently in the second sentence. 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 zero-parameter, read-only tool with no output schema, the description is complete: it lists what the response contains, explicitly notes what it excludes, and names the exact sibling tools for related use cases. An agent has enough information to call it correctly.

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

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

The tool has zero parameters, and the schema confirms no required or optional parameters. With no parameters to document, the description does not need to add parameter-level semantics; the baseline for zero-parameter tools is appropriate here.

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

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

The description clearly identifies the tool as retrieving the business's own profile and enumerates its contents (name, contact details, industry, currency, tax rate, plan). It explicitly distinguishes itself from get_financial_summary and get_business_overview, so an agent can tell them apart without inspecting other definitions.

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

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

The description provides explicit usage guidance: financials are excluded, and the agent is directed to get_financial_summary for financials alone or get_business_overview for both profile and financials in one call. This clearly communicates when to use this tool versus the alternatives.

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

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

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.

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 a genuine behavioral detail beyond that: ids are scoped to the current business and an out-of-scope id raises an error rather than returning empty/404 semantics. It still says nothing about response shape, pagination, or side effects (none expected).

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, zero filler, with the core identity ('one pay run by id') front-loaded and the constraint trailing. Nothing repeats the title or annotations.

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-param read tool with annotations covering safety, the description covers what is needed; the 'same fields as list_payruns' note usefully compensates for the absent output schema. It does not say what happens for a malformed id, but that 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 description coverage is 0% for the single required 'id' param, so the description must carry the load. It clarifies that id identifies a pay run belonging to this business, which adds scoping meaning beyond 'type: string', but gives no format hint (e.g. numeric vs opaque string).

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?

Clear verb+resource ('One pay run by id') and it explicitly relates itself to the sibling 'list_payruns' by stating it returns the same fields. An agent can tell it fetches a single pay run rather than enumerating them, though it does not spell out the single-vs-list choice as a routing rule.

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: fetch one pay run when you already hold its id. There is no explicit 'use this instead of list_payruns when...' guidance, but the error note about non-owned ids gives the agent a usable precondition.

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 genuinely useful behavior: the returned field set matches list_payslips (compensating for the absent output schema) and a tenant-scoping rule that a foreign id is an error. It stops short of describing the not-found error explicitly.

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 action and followed by the return-shape and error-scope facts. No filler; every clause adds 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 one-parameter read tool with no output schema, the description covers return shape (same as list_payslips) and the tenancy error condition. It is nearly complete; the only gap is the precise not-found error semantics and any pagination/adjacent concerns, which do not apply 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 0% for the single 'id' parameter, so the description carries the burden. It partially compensates by declaring the id is scoped to this business's payslip (an out-of-scope id is an error), but gives no format or type detail, which is typical for an id field but still a gap.

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

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

States a specific verb and resource ('One payslip by id') and explicitly contrasts with the sibling list_payslips by noting field parity. An agent can distinguish single-fetch from list without opening the schema, though it does not distinguish itself from the other payslip siblings (save_payslip, delete_payslips).

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 only implied: 'one payslip by id' suggests a single-record fetch versus list_payslips, but there is no explicit when-to-use/when-not guidance or named alternative beyond the implicit contrast. Adequate but leaves routing to inference.

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

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

The annotation declares readOnlyHint=true, and the description does not contradict this. It mentions reading from live or snapshot sources, but does not add additional behavioral details like rate limits or side effects, which is acceptable given the annotation.

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

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

The description is two sentences, front-loads the primary purpose, and uses precise domain terminology. 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?

The description lists the expected data fields (bucket, direction, capital, etc.) and mentions pagination implicitly via the schema's cursor/limit parameters. It does not describe the output format explicitly, but given the tool's simplicity and the schema coverage, it is sufficiently 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 already thoroughly explain each parameter (e.g., periodEnd is required for live, defaults for snapshot). The tool description adds little beyond a conceptual 'flow filter' reference, but does not improve on the schema's clarity.

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

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

The description states it returns per-entry sales-tax classifications for a period, and emphasizes it is the single feed every tax report reads. It also distinguishes live vs snapshot modes, making the purpose unambiguous.

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

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

It explains that it serves as the single feed for tax reports, and clarifies when to use live books (via period filters) versus a snapshot (via snapshotid). It does not explicitly compare to sibling tools, but the guidance is sufficient for typical use cases.

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 well beyond the readOnlyHint annotation by explaining what data is contained, including carry-forward/variant/detail codes, personal deduction rules, and trade source-code rules. It also reveals behavioral traits like stability and business-independence, which supports caching and repeated reuse. No contradiction with annotations.

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

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

The description is a single dense sentence that front-loads the core purpose and then enumerates the specific table contents without filler. It is longer than average, but the density is justified by the richness of the data being described; only modest restructuring would improve scannability.

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

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

For a read-only reference lookup with one optional parameter and no output schema, the description is complete: it states what data to expect, the country scoping, the stable read-once usage guidance, and the specific sub-categories the agent will encounter. Nothing needed for correct invocation is missing.

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

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

The input schema fully documents the single optional country parameter, including its default behavior. The description reinforces the locale-related scope with the ZA example but does not add substantial meaning beyond what the schema already states, so the baseline score 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 defines the tool's exact resource: the statutory source codes a locale's returns print, with a concrete example (ZA ITR12) and enumerated sub-tables such as the 4000-series Other Deductions table and rental profit/loss codes. This level of specificity makes it unambiguous even among many sibling tools.

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

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

The description gives clear usage guidance: this is reference data that is business-independent and stable, so it should be read once rather than per report. It does not explicitly name alternatives or describe when not to use it, but the guidance provided is actionable and relevant.

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 tells the agent this is a safe read. The description adds only content scope ('line items', 'plan they pay stub for') and no behavioral context such as whether the subscription is current, whether line items are historical, or whether anything is paginated. With annotations covering the safety profile, a 3 is appropriate.

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 resource before listing the alternatives — good structure with no padding. It loses a point because the 'stub subscription / the plan they pay stub for' repetition is confusing rather than economical.

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 no parameters, so the description is the only source for what comes back, and it only vaguely gestures at 'subscription / billing line items' without describing the shape (plan, price, line items, period). Complexity is low, but for a no-schema read tool the return scope should be pinned down better than 'stub subscription'.

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 (empty schema, nothing required), so there is no parameter semantics for the description to clarify. Baseline 4 applies — there is simply no gap to fill.

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 resource is identifiable — the business's subscription/billing line items — and the description explicitly separates itself from three siblings (get_action_usage, get_business_profile, get_financial_summary). However, there is no verb and the phrasing 'stub subscription ... the plan they pay stub for' is muddled enough that an agent may be unsure whether this returns a plan, a billing line-item list, or both.

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 names three concrete alternatives and the condition that selects each (actions used this period → get_action_usage; profile → get_business_profile; financials → get_financial_summary), which is real routing guidance. It stops short of stating when this tool itself is the right call (e.g. for reviewing plan tier or seat count), so it is clear context rather than a full when/when-not spec.

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 already covers the read-only nature. The description adds that it returns specific member fields but does not mention any additional side effects, authentication, or rate limits. Given the annotation, the bar is lower, and this is sufficient.

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

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

The description is a single, precise sentence with no extraneous information. It is well-structured and front-loaded with the main action.

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

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

With no output schema, the description names the key fields returned (name, email, role, active status), which is adequate for basic usage. It could optionally mention whether it returns all members or only active ones, but it is not a significant 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?

The tool has zero parameters, so there is nothing to explain beyond what the schema shows. Baseline score of 4 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 it retrieves the business's team or members with specific fields (name, email, role, active status). It is distinct from other tools by focusing on the team roster.

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 explicit guidance on when to use this tool versus alternatives. While the name and description imply it is for fetching team information, it does not state conditions or preferences.

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 reveal readOnlyHint=false and destructiveHint=false. The description adds substantial context: it acts 'as them', attaches the case for the team, opens the support chat, and discloses failure behavior ('Check `sent`: when it is false nothing reached the team'). This is behavioral detail well 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?

Front-loaded with the core action, then usage rules, then the important `sent` caveat. All sentences earn their place, though the enumeration of trigger cases is dense. Slightly long but efficiently 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, the description compensates by explaining the side effects (opens a support conversation, opens chat) and how to verify success via `sent`. Combined with the explicit usage policy, an agent has everything needed to call this 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 schema already documents all six parameters (kind, found, tried, chatid, reason, question). The description adds only a soft implication that 'the case' is built from found/tried, and introduces the `sent` field which is a return value rather than a parameter. Baseline 3 is appropriate when the schema carries the load.

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 ('Hand the question to the support team with the case written') and a customer-facing benefit. Clearly distinguishable from sibling communication tools like send_feedback or send_team_feedback, since it opens a support conversation on the customer's behalf.

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 allow-list ('ONLY when a person must act: they asked for a person, a refund, a legal or privacy request, something broken..., money moved, account access') and an explicit exclusion ('Never to avoid a hard question'). The when/when-not criteria are unusually complete.

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

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

Annotations only mark this as non-read-only and non-destructive, but the description discloses meaningful behavior: it is atomic, it restores soft-deleted entries rather than duplicating them, it only creates a fresh entry when none existed, and it is idempotent on retry. This is exactly the kind of side-effect information an agent needs beyond 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 deliver the purpose, the core behavioral guarantee, and retry safety without repetition or fluff. The most important information is front-loaded in the first sentence. Every sentence 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 single-parameter invocation with no output schema, the description covers what the tool does, what happens to existing entries, when a new entry is created, and retry semantics. An agent has enough information to decide whether to call it and to predict the outcome of doing so.

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

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

There is only one parameter, ids, and the schema already covers it completely with a description. The tool description adds context about the bulk/atomic nature but not new detail about the parameter itself. Since schema description coverage is 100%, 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 begins with a specific verb and resource: 'Include (un-ignore) many bank transactions in one atomic call.' It further clarifies by naming its relationship to exclusion and explaining the intended effect on transactions. This makes the tool's purpose unambiguous and distinguishable from the broad sibling list.

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

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

The description clearly communicates that this tool is for including previously excluded transactions and that it is the inverse of excluding them. It also explains safe-to-retry behavior, which gives the agent practical usage context. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full alternative 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?

The description adds a useful behavioral detail (fails cleanly on missing records) beyond the annotations. However, it does not mention whether the operation is idempotent, whether it overwrites existing links, or any other side effects, so transparency is partial.

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 very concise, consisting of two sentences with the core purpose stated first and a relevant failure behavior second. No superfluous content is present, and the structure is effective.

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 four-parameter mutation with no output schema, the description adequately covers the main behavior. It mentions the failure case, but omits details about success return values or constraints on supported pairs (beyond examples), which could be useful but are not critical.

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

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

The schema already provides descriptions for all four parameters (100% coverage), and the tool description does not add significant extra meaning beyond the schema text. The examples in the description (e.g., 'income+transaction') give some context but don't materially enhance parameter understanding.

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

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

The description clearly states the action ('Link two entities') and provides examples of supported pairs, making the purpose understandable. However, it does not explicitly distinguish itself from the sibling tool 'unlink_entities', relying on the verb alone to convey the opposite action.

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

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

It implies usage for creating links between entity pairs and notes the failure behavior, but does not explicitly state when to prefer this over alternatives (e.g., unlink_entities) or mention any preconditions beyond existence of the records.

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 aligns with the readOnlyHint annotation and makes no conflicting claims; it adds context that the tool is a public store but does not describe side effects beyond the annotation.

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

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

The description is compact, focused, and front-loads the core purpose and distinction from installed apps without unnecessary 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?

It describes what the tool returns (each app's id, name, description, category, region, and connection config) and clarifies its scope, making it complete for a parameterless read-only listing tool.

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

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

The tool has zero parameters, matching the schema; with no parameters there is nothing to explain, so the baseline of 4 applies.

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

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

The description clearly states the tool lists the public catalogue of integrations (apps) a business can connect, identifies the included fields, and explicitly distinguishes it from installed apps.

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

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

It provides a clear when-not-to-use by stating this is the public app store, not the business's installed apps, but does not explicitly name an alternative 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 declare `readOnlyHint: true`, and the description adds the further behavioral detail of deletion-time ordering, plus the non-obvious edge case that payments associated with a deleted document are hidden from this listing and only reappear after restore. It does not contradict the annotation and adds useful semantic behavior beyond the schema.

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

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

The description is two sentences: the first front-loads the main action and scope, the second adds the crucial edge case. There is no filler, and every clause adds information directly useful to deciding and invoking the tool.

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

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

For a zero-parameter, read-only list operation without an output schema, the description covers everything an agent needs: what is listed, what is excluded, and the ordering. The payment caveat also prevents a realistic misunderstanding about what shows up in the result set.

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

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

The tool has zero parameters, so there is nothing for the parameter schema to explain. The absence of any parameters is accurately reflected by the empty `properties` object, and the description does not need to elaborate on parameter usage.

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

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

The description states a specific verb ('List') and a precise resource ('binned soft-deleted records'), then enumerates all covered record types and specifies sorting ('newest deletion first'). It clearly distinguishes this list tool from brothers that list active records (list_invoices, list_clients, etc.) by its exclusive focus on binned items.

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

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

It provides a clear context: use this to see binned records for the business, and it adds an important functional caveat that binned document payments are not separately listed but will be restored with their document. It does not explicitly name alternatives like `restore_deleted` or state 'when not to use it', but its purpose itself implies the use case.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: archived customers are included and carry 'archived: true', with the note that archiving hides nothing server-side. This clarifies a potentially surprising behavior. The description also implies pagination via schema but doesn't repeat it. Overall, it adds meaningful behavioral disclosure beyond the annotation.

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

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

The description is two sentences with no fluff. The core purpose is front-loaded, and the archive behavior is succinctly appended. Every word adds value; there is no redundancy or irrelevant 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?

The tool has 5 parameters and no output schema, but the schema itself thoroughly documents each parameter. The description covers the main output fields and the archive behavior. It doesn't explain the return structure (e.g., pagination fields) but the schema does, so the description is adequately complete for an agent to call it correctly. Minor gaps like mentioning the default limit are already in the 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%, meaning all parameters (to, from, limit, query, cursor) have detailed descriptions. The tool description itself does not add further parameter semantics beyond what the schema provides. Per calibration, high coverage leads to a baseline of 3, and the description does not need to compensate.

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

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

The description clearly states the action ('List'), the resource ('customers'), and the specific fields returned (id, name, email, invoiced/outstanding totals). It distinguishes itself from sibling tools like list_suppliers or list_accounts by explicitly naming 'customers' and the business context. The archive behavior is also clearly noted, adding specificity.

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 does not explicitly state when to use this tool versus alternatives (e.g., list_suppliers, list_invoices). It provides context about including archived customers but offers no guidance on when this tool is preferred or when another list tool should be used. The purpose is clear, but there's no explicit routing 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?

Beyond the readOnlyHint annotation, it discloses pagination behavior (50 per page, 200 max), newest-first ordering, the meta.total/truncated pitfall, and that it reads both document stores. It also explains that rows carry totals/outstanding/status fields, which matters because 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?

Although long, every clause earns its place: purpose first, then the pagination warning, filters with examples, row fields, and the handoff to get_document. The potential wall-of-text is justified by a 12-parameter tool and is front-loaded with the most important caveat.

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

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

For a list tool with no output schema, it covers pagination, filter combinations, ordering, row contents, and the alternative for full detail. Nothing needed to call the tool correctly or interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is already strong. The description adds value by grouping the filters, clarifying the query substring semantics, and giving ready-made combinations. It doesn't go deep on every parameter, but the schema already handles those details.

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

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

The opening sentence names the verb ('List') and the exact resource ('the business's documents'), enumerates every document type, and asserts it is the complete authoritative surface reading both document stores. This also distinguishes it from narrower list tools such as list_invoices and from get_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 gives explicit routing guidance ('Use get_document for one document's full detail') and concrete composition examples (type=bill + unpaid + status=overdue, or type=invoice + query=<ref>). It does not explicitly name the 'when not to use' cases for sibling list tools like list_invoices or search_combined, but the context is clear.

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