Otis

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

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=false), and the description is consistent with them via 'create or replace'. It adds genuine domain rules — AI usage must be measured or estimated, amounts and rates are never invented — but never states what the replace path overwrites or whether existing linked records are affected, which matters for 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?

Five short sentences that are front-loaded with the primary action and each carry a distinct rule (item_id, expense_record routing, kinds, minor units, measurement honesty). Some fragments read telegraphically and the kind list restates the enum, but there is little actual waste.

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

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

For a destructive, idempotent mutation with 13 parameters, 7 of them required, 15% schema coverage and no output schema, the description leaves major gaps: no return-value expectations, no overwrite semantics, no note on which fields are required or how request_id drives the idempotent retry, and no mention of the business_id scoping that the schema touches only briefly.

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

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

Schema description coverage is only 15%, so the description must carry parameter meaning and it largely does not: quantity, unit, client_id, reference, cost_minor, rate_minor, business_id and request_id get no mention. It does clarify `item_id` usage, that the price is in minor units (`amount_minor`), and that `measurement` applies only to AI usage — useful but far short of compensating for 13 mostly undocumented 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?

Opens with a specific verb+resource ('Create or replace unreserved, uninvoiced work') and enumerates the supported kinds (time, reimbursable expense, AI usage), which maps directly to the `kind` enum. It also distinguishes itself from the sibling `expense_record` for linked expenses. The 'replace' half of the verb is not defined (replace what key? by item_id or request_id?), which keeps it short of a 5.

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 a concrete boundary ('unreserved, uninvoiced work') and routes a specific case to an alternative tool ('Linked expenses must be edited with expense_record'). It does not cover other plausible siblings such as timer_start/timer_stop for capturing time, so the alternative-routing is partial rather than 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 already establish read-only, idempotent, non-destructive behavior. The description adds non-obvious domain behavior: partially billed or reserved items can still have remaining_minor available for new invoices, and state=unbilled is not a sufficient filter by itself.

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 front-loads the core purpose before the important state caveat. It is short, dense, and wastes no space on repetition.

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

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

The key billing caveat is present, which is important, but with no output schema and only 20% parameter schema coverage, the description should do more to explain the remaining parameters and what the returned billable items contain.

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

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

Schema description coverage is only 20%, with only business_id documented in the schema. The description adds meaning for the state filter, but it does not explain limit, offset, or client_id, so it does not compensate for the low schema coverage.

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

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

The description states a clear verb and resource: 'Find billable items.' It is understandable without opening the schema, but it does not explicitly distinguish this from siblings such as billable_record or invoices_list.

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

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

It gives a useful usage caveat for invoicing: remaining_minor is available for new invoices, including partially billed or reserved items, and warns not to rely on state=unbilled alone. However, it does not explicitly say when to use this tool versus alternatives like billable_record or invoices_list.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful default-business-resolution rule, but says nothing about result shape, result size, or what happens when the caller belongs to multiple businesses.

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 primary purpose front-loaded and the fallback rule second. Nothing is padded and nothing repeats the title.

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

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

There is no output schema, so the description should at least hint at what a listed business contains and how many come back per page; it does neither. It is adequate to trigger the call but thin for a tool whose entire value is returning IDs the agent will reuse elsewhere.

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

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

Schema description coverage is 0% and the two parameters (limit, offset) are undocumented, so the description must compensate and does not — pagination is never mentioned. An agent cannot tell from either source that these control page size and paging offset.

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 concrete goal (find your business and its business_id), which is more useful than a bare 'list'. It implicitly separates itself from business_get by framing the tool as the way to discover an ID rather than fetch a known one, though it never names 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 second sentence gives real cross-tool guidance: omit business_id elsewhere to fall back to your own business, which tells an agent why this lookup matters. However, it never says when to use this versus business_get or business_set, leaving the sibling choice 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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing what data is returned (identity, currency, tax profile, next setup step), which matters since there is no output schema — though 'next setup step' remains vague.

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

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

A single economical sentence with the verb and returned data front-loaded. The trailing 'or the next setup step' is slightly loose but does not waste much space.

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 low-complexity single-optional-param read tool with full annotation coverage and no output schema, the description covers the main returned artifacts. It stops short of explaining what 'next setup step' contains or how multiple aspects are selected, but nothing critical 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?

Single optional parameter at 100% schema description coverage, and the schema itself carries the meaningful guidance about omitting it or getting shared IDs from businesses_list. The description adds nothing about business_id, which is acceptable given the schema does the work.

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 enumerates the resources returned: identity, currency, tax profile, and next setup step. This distinguishes it implicitly from business_set (writes) and businesses_list (enumerates IDs), though it never names those siblings explicitly.

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 on when to call this versus businesses_list or business_set, and no stated preconditions. The only usage hint ('Omit for your own business; use businesses_list for shared business IDs') lives in the schema, not the description, so the description itself gives no routing help.

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 by disclosing replace semantics for the top-level fields, that tax profile and omitted invoice preferences survive the write, and two irreversible lock rules (starting number locks after first issuance; currency locks after financial records exist). Those lock facts are exactly the irreversible side effects that destructiveHint=true only hints at.

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 short, front-loaded sentences with no filler: identity/scope first, then preservation, then optional capabilities, then locking constraints. Slightly telegraphic phrasing ('Owner: create or replace...') but nothing is redundant.

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, idempotent, nested-object mutation with no output schema, the description covers scope, preservation, and irreversibility well. It never states what the call returns or how a partial update interacts with fields outside the listed set, which is the remaining gap.

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

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

Schema description coverage is only 33%, but the description names every nested invoice_preferences field (prefix, padding, starting number, default note, payment instructions) plus the address, compensating for the gap. The two undocumented-by-description params (request_id, business_id) are the ones the schema itself already describes.

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 ('create or replace business name, currency and address') and scopes it to the owner, which separates it from business_get/businesses_list reads and from tax_profile_set (whose data it explicitly preserves). The fields it writes are enumerated, so an agent can tell immediately what this tool mutates.

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 'Owner:' prefix and 'using confirmed facts' set a precondition (caller must own the business and must have verified values), and the note about preserving tax profile implicitly routes tax changes to the sibling tool. No explicit when-not guidance or named alternative is given, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description's 'replace' wording is consistent with that. It does not disclose what a replace overwrites (e.g., whether omitted fields such as tax_ids or billing_address are cleared) or that request_id drives retry safety, which is where the annotation bar is not met.

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

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

Two tight sentences: the action is front-loaded, then the data-collection rule. No filler, though the second sentence packs two ideas (what to collect and what never to infer) into one clause.

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

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

Given a destructive mutation with no output schema and low schema coverage, the description covers purpose and one critical domain rule but omits the create-vs-update mechanics that an agent needs before writing. Incomplete for a 12-parameter destructive tool.

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

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

Schema description coverage is only 17% out of 12 parameters, so the description must compensate and does not. It adds real meaning for country, region and customer_type (tax-review purpose, no currency inference) but leaves client_id, tax_ids, tax_evidence, billing_address, postal_code and email entirely unexplained.

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

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

States a specific verb+resource pair ('Create or replace client details') that an agent can distinguish from clients_list or business_set. 'Create or replace' hints at upsert semantics but doesn't say which field selects the mode.

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?

Implies the context (invoice tax review) and gives one negative rule ('never infer these from currency'), but names no alternatives and gives no condition for creating a new client vs. updating an existing one via client_id.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered elsewhere. The description adds pagination behavior, but it references 'next_offset', a field that does not exist in the input schema (which uses offset/limit) and is not explained as a response field, leaving the paging mechanics slightly ambiguous.

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

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

Two short sentences with the core purpose front-loaded and no filler. The only cost is that the second sentence introduces a field name that is not defined in the schema, adding a small ambiguity rather than clarity.

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

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

No output schema exists, so the description should say more about what a client record contains and how pages are signaled; instead it only hints at next_offset. Given there are three optional parameters and no annotations gaps to fill, this is adequate but thin.

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

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

Schema description coverage is only 33%: only business_id is documented in the schema, while limit and offset have no descriptions anywhere. The description does not compensate by explaining default page size, maximum, or offset semantics, so an agent must infer them from raw constraints.

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

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

The description gives a specific verb and resource ('List client records'), which maps cleanly to the tool name and separates it from mutating siblings like client_save. It stops short of explicitly naming sibling alternatives, so it is clear but not fully differentiated.

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

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

The pagination instruction ('Follow next_offset to retrieve every page') tells the agent how to iterate, which is real usage guidance. However, there is no statement of when to use this versus businesses_list or other listing tools, and no prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, and the description still adds substantive behavior: linked billables update atomically and become immutable once reserved or invoiced. That immutability rule is not derivable from the annotations or schema and is the most valuable sentence here. It does not say what happens to an existing expense's unmentioned fields on replace, nor anything about failure/partial-write 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?

Three tight sentences with the create-vs-replace rule front-loaded. The final clause about billable_amount_minor is dense and slightly ambiguous in referent ("one linked billable item"), 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?

For an 11-parameter destructive mutation with no output schema, the description covers the highest-risk semantics (atomicity, post-reservation immutability, no double-recording) but leaves most fields and the create-vs-replace field semantics undefined. Adequate, 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?

With only 18% schema coverage, the description must carry most parameter meaning; it explains three of eleven (expense_id, client_id, billable_amount_minor) but says nothing about vendor, category, description, incurred_on, cost_minor, reference, or which fields are required. request_id idempotency is documented in the schema, not the description. Useful but far from compensating for the coverage gap.

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

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

States a specific verb pair (create or replace) plus the resource (business expense) and the key discriminator (expense_id determines which). It is clearly distinct from expenses_list and billable_record, though it never names those siblings explicitly.

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?

"Create or replace ... using expense_id" implicitly tells the agent that supplying expense_id means update, omitting it means create. The closing instruction "do not record it again" steers the agent away from calling billable_record separately for the same amount, which is real routing guidance. No explicit when-not for the tool as a whole.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds useful content context (nonbillable costs included, billable IDs linked) but says nothing about ordering, pagination behavior, or what a returned expense looks like.

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

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

A single front-loaded sentence with no filler. Its brevity is efficient, though it leaves real gaps that a slightly longer description could have closed.

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 four optional parameters, pagination semantics, no output schema, and only 25% schema coverage, the description does not tell an agent how to page, how to scope by client, or in what order results come back. For a listing tool whose output shape is undocumented, this is materially incomplete.

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

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

Schema description coverage is only 25% — only business_id is documented in the schema, while limit, offset, and client_id carry no descriptions. The tool description mentions no parameters at all, so it fails to compensate for the coverage gap on pagination and client filtering.

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 (List) and resource (recorded expenses), and adds scope detail: nonbillable costs and linked billable item IDs are included. That distinguishes it from a billables-only listing, but it never names the sibling it differs from (billables_list, expense_record), so an agent still has to infer the boundary.

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

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

The scope wording ('including nonbillable costs') implies this is the general expense listing rather than a filtered billables view, but there is no explicit when-to-use, when-not-to-use, or named alternative such as billables_list or expenses via expense_record. Usage 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 already declare readOnly=false, openWorld=true, idempotent=true, destructive=false, but the description goes far beyond: it discloses a 20/day per-person rate limit, role-agnostic access, exactly what data leaves the client (only message, kind, client – never business records or chat history), and the show-then-approve protocol. This is rich, non-redundant behavioral context.

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

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

Purpose is front-loaded, followed by usage triggers, the approval protocol, consent, data-scope, and limits. Dense but every sentence carries actionable constraints with no padding.

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

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

For an outbound feedback tool with no output schema, the description supplies everything an agent needs: invocation triggers, consent requirements, data boundary, rate limit, and the approval gate. Nothing material is missing.

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

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

Schema coverage is 80%, so the schema documents most params. The description adds consent semantics for reply_ok ('ask before setting... shares their verified email') and reinforces that the message must be the exact user-approved text, adding meaning beyond the field docs.

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 ('Send feedback to the Otis team') and enumerates the message kinds. Easily distinguishable from the business/invoice/payment siblings since this is the only user-feedback channel.

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

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

Explicitly covers when to offer it ('user wants something Otis cannot do, asks for a feature or hits a problem'), when not to ('never send unprompted'), and the required approval workflow. It also flags the reply_ok consent step, leaving nothing 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 already declare destructiveHint=true and idempotentHint=true, so the agent knows this is an irreversible-but-retry-safe mutation. The description adds genuinely new context: that allocations are released and that the operation is scoped to unissued drafts only. It does not mention permission requirements or whether the cancelled draft is retained for audit, which keeps it below a 5.

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

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

Three short sentences, zero filler, with the core action and its side effect front-loaded before the use case and the constraint. Nothing needs to be trimmed.

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 4-parameter mutation with no output schema, the definition covers the essential scope but leaves open what the tool returns, what happens to the cancelled draft record afterwards, and what the required reason field is for. Adequate but with real gaps an agent would have to discover by calling.

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%: request_id and business_id are documented in the schema, but invoice_id and reason have no description anywhere. The description indirectly constrains invoice_id to an unissued draft, but says nothing about why a free-text reason is required or how it is used, so the gap is only partly compensated.

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 ('Cancel an unissued draft') plus the side effect ('release all its allocations'), which is far more than a restatement of the title. The draft-vs-issued boundary implicitly separates it from invoice_issue and invoice_get, though no sibling is named outright.

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?

'Use to rebuild a draft with corrected facts' gives a concrete use case, and 'Issued invoices cannot be changed' is an explicit when-not condition. It stops short of naming the follow-on tool (e.g. invoice_draft) the agent should call to recreate the draft.

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 read-only/idempotent/non-destructive/closed-world, so the description's value is in the substantive caveat: 'Success validates recorded fields, not legal tax compliance' — a real expectation-setter about what a pass means. It also discloses the shape of the result (blockers plus a next_tool), which 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?

Three short sentences, no filler, with the core action and the result shape front-loaded. Every clause carries information the agent cannot get from structured fields.

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

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

No output schema exists, so the description must signal return content — it does at a high level (blockers, next_tool) and flags the compliance caveat. It stops short of describing what a blocker entry looks like or the behavior on a failed check, which leaves a small 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?

With schema coverage at 50%, the schema documents business_id (omit for own business; use businesses_list) but leaves invoice_id bare, and the description adds nothing about either parameter. Baseline 3 applies since the ambiguity that matters is already handled in the schema.

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

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

States a specific verb and object: 'Check issuance readiness', returning blockers and their next_tool. It is clearly a pre-flight validation step distinct from invoice_issue, though the description itself never says 'invoice' — that only comes from the tool name and title.

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

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

Usage is implied rather than stated: 'Read blockers and their next_tool' points at a follow-up chain, and 'ask the user for missing facts' tells the agent what to do with results. But it never says explicitly to call this before invoice_issue, nor when it can be skipped.

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 write, idempotent, and destructive, and the description adds the useful fact that billable amounts get reserved and that the draft is unnumbered with validation feedback returned. However, it doesn't reconcile the 'just a draft' framing with destructiveHint=true (there is an invoice_cancel_draft sibling, but no statement about reversibility or side effects on billables), which is context an agent would want before calling a mutating 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?

Four short front-loaded sentences, no filler; the amount/tax/discount/return information comes in the order an agent needs it and the terse 'No number assigned.' earns its place by disambiguating draft from issue.

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

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

There is no output schema, and the description compensates by stating that totals and missing-information feedback are returned, which is exactly what an agent needs to know about the draft response. Remaining gaps are the lack of any error/permission guidance and the unstated handoff to invoice_issue.

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

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

Schema coverage is only 25%, so the description must carry the load — and it does on the hardest parts: it explains partial amounts against billable items, per-line tax treatments, and both line-level and invoice-level optional discounts, matching the deeply nested tax object and discount oneOf. It adds no guidance on supply_date/due_date, client_id, business_id, or request_id retry semantics.

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

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

Specific verb and resource: 'Reserve explicit amounts from billable items, including partial amounts' plus 'No number assigned' clearly frames this as the draft stage of an invoice. It implicitly distinguishes from invoice_issue, though it never names a sibling directly.

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 rather than stated — 'No number assigned' and the draft framing suggest this precedes invoice_issue, but the description never says when to draft versus issue, check, or go straight to billables_list. No explicit exclusions or prerequisites.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description does add real nuance — invoice contents are "immutable" while the payment balance is a "current reported" figure, warning that balance is live rather than part of the snapshot — but it says nothing about permission requirements for shared businesses or behavior on a missing/invalid ID.

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

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

A single front-loaded sentence that packs the resource, the immutability qualifier, and the returned fields with zero redundant wording.

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 burden of describing return contents and does so by naming four distinct data groups. It is nearly complete for a two-parameter read tool, missing only edge-case behavior and the ID sourcing hint that already lives 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 description coverage is only 50%, and only business_id carries schema text (omit for your own business, use businesses_list for shared IDs). The description adds nothing about invoice_id formatting or scoping, so it fails to compensate for the uncovered parameter.

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

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

The description gives a specific verb ("Read") and enumerates the returned resources (invoice contents, source allocations, tax details, payment balance), which clearly separates it from the list/aggregate siblings such as invoices_list and invoice_check. Sibling differentiation is implicit via the singular resource rather than named alternatives.

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

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

Usage is implied by the verb "Read" plus the singular invoice resource, so an agent can infer this is the per-invoice detail lookup. However, it never states when to prefer it over invoice_check, invoices_list, or invoice_cancel_draft, nor does it note any precondition such as the invoice needing to exist.

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

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

Annotations already flag destructive=true, idempotent=true and non-read-only, so the bar is lower, yet the description adds real context: it blocks on missing facts and atomically assigns a number. It does not spell out what an atomic failure looks like or whether numbering is irreversible, leaving a small 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?

Two compact sentences, no filler: the precondition and the atomic numbering behavior come first, then the scope exclusions. Every clause carries operational meaning for the agent.

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 5-param, destructive, idempotent mutation with no output schema, the description supplies the gating condition, validation behavior, atomicity, and explicit non-goals; return value need not be described since no output schema exists and the key outcome (assigned number) is stated.

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 60%, and the description compensates by tying the call to the user-approved "total" (expected_total_minor) and the confirmation gate (confirmed). It does not clarify request_id retry semantics or business_id scoping, but the schema covers those directly.

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?

Specific verb+resource: "Finalize a draft" invoice, with the exact precondition (user approval of contents, tax treatment, total). The closing sentence explicitly disclaims adjacent capabilities (sending the document, certifying tax compliance), which separates it from invoice_draft and any send/tax tools in the sibling list.

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

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

Clearly states the trigger condition — only after the user approves the exact contents and total — and implies the prerequisite draft-creation sibling without naming it. It also states a negative boundary (does not send or certify tax). No alternative tool is named by name, so it falls just short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds one genuinely useful behavior detail — that responses carry a next_offset pagination cursor — but says nothing about result size, default limits, or whether filters combine.

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 resource and scope. Nothing is wasted, though "Follow next_offset" is terse to the point of ambiguity about where that field appears.

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 75% of parameters undocumented, the description should explain the returned shape (fields, cursor location) and the filter semantics. It alludes to next_offset but never defines the response or the filtering model.

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

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

Schema coverage is only 25%: only business_id is described in-schema, leaving limit, offset, and the status enum undocumented. The description does not compensate — it never mentions status filtering (the one enum), page-size limits, or how offset relates to next_offset.

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 concrete verb+resource (list invoices) and adds a distinguishing scope note ("with reported balances"). It doesn't explicitly contrast with invoice_get or siblings like billables_list/payments_list, but a reader can tell this is the collection endpoint rather than the single-invoice endpoint.

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 on when to use this versus invoice_get or the other *_list tools, and no mention of how to narrow results. "Follow next_offset" implies pagination but not the conditions for calling the tool at all.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description earns extra credit by disclosing the return shape (nine independent actions with tool mappings) and that no business records are read or mutated, plus the interaction protocol of pausing for the user's selection.

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 the action and triggers, then scope, then the required follow-up behavior. No filler or restated field names.

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 job of saying what the agent receives — it does exactly that (nine actions, mapped tools, workflow guidance) and adds the interaction expectation. Nothing needed to call a zero-arg menu 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?

The tool takes zero parameters, so the schema baseline of 4 applies and there is nothing further for the description to disambiguate.

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 — 'Show the Otis chat menu' — and pins the triggers (/otis, 'show Otis menu', getting started). It also declares what comes back (nine actions with mapped tools plus workflow guidance), which separates it from every sibling tool that actually touches records.

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 concrete invocation triggers and a clear scope boundary ('without reading or changing business records'), plus the follow-up instruction 'Wait for the user's choice.' It doesn't explicitly name a sibling as the alternative, but the entry-point framing makes the when-to-use obvious.

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 meaningfully beyond the annotations: it discloses the trust model ('reported', no bank verification), the double-counting guard via a business-wide unique reference, and the overpayment rejection rule. It does not explain what the destructiveHint=true actually destroys (e.g. invoice status/outstanding balance changes), which is the one notable 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?

Four short sentences, each carrying a distinct fact: scope, deduplication, overpayment rule, and absence of verification. Front-loaded with purpose and zero padding.

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

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

For a destructive, idempotent mutation with no output schema, the description covers trust and duplicate-prevention but leaves out downstream effects (does a full payment close the invoice?), permission requirements, and response shape. Adequate but with clear gaps an agent would want filled.

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

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

With only 50% schema description coverage, the description compensates partially: it clarifies that amount_minor may be a partial or full amount and that overpayment is rejected, and reinforces reference uniqueness. It says nothing about invoice_id, received_on, or business_id semantics beyond what the schema already implies.

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 ('Record a ... payment for an issued invoice') with the important qualifier that the payment is 'reported' and the invoice must already be 'issued'. This distinguishes it from expense_record and billable_record by implication, but does not name those siblings or payments_list explicitly.

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 rather than stated: the tool is for reporting a payment against an issued invoice, and the 'reported'/'no bank verification' framing hints it is a manual reconciliation entry rather than a gateway charge. There is no explicit when-not-to-use and no pointer to alternatives such as payments_list for reading records or expense_record for outbound money.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds essentially nothing beyond the name/title: no ordering, pagination behavior, or what "reported" means (e.g., only confirmed vs. pending payments).

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 short sentence, front-loaded with the resource and the optional filter; nothing is wasted. It is terse, but the terseness problem is captured under completeness rather than 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?

Four parameters, no output schema, and only one parameter documented in the schema; the description should at least cover pagination defaults and the meaning of the optional filter scope, but leaves those to inference.

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

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

Schema description coverage is only 25% — limit, offset and invoice_id carry no description in the schema. The description mentions invoice_id filtering but says nothing about limit/offset pagination semantics or defaults, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ("List reported payments") plus an optional scope ("for one invoice"). An agent can distinguish it from the sibling payment_record (which writes) and invoices_list (different resource), though it never names the sibling that creates payments.

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

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

The phrase "optionally for one invoice" implies the main filtering use case, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as payments_list vs. invoice_get for fetching payment data for an invoice.

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 readOnly, idempotent, and non-destructive, so the bar is lower. The description adds genuinely new behavior: pagination as the delivery mechanism, a termination condition, and the permission tier required — though the referenced 'next_offset' does not appear in the input schema, leaving the loop instruction partly unverifiable.

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 returns and how pagination works. Nothing is padded, though the mismatched 'next_offset' name wastes one of the few sentences on a non-existent parameter.

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 must carry the return-shape burden; 'paginated JSON' plus a next_offset instruction is thin and internally inconsistent with an integer `offset` input. It also leaves the enum breadth and the relationship to the sibling list tools unexplained, so an agent cannot confidently choose between them.

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

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

Schema description coverage is only 25% — only business_id is documented (by the schema itself). The description does not explain the eight `kind` values, the limit cap of 100, or the meaning of offset; instead it references 'next_offset', a field name that does not exist in the schema. It adds almost nothing beyond the structured data.

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: export records/audit history as paginated JSON. However, the stated scope ('business records and audit history') undersells the `kind` enum, which also covers client, billable, expense, timer, invoice, payment — and it never distinguishes itself from sibling list tools like invoices_list or expenses_list that surface the same resources.

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

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

There is no guidance on when to choose this over the many *_list siblings, nor any prerequisite or exclusion. The only routing-adjacent statement is a permission note ('Viewers can read/export'), which is not usage guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds meaningful traits on top: the content is dated and official-source, and it is advisory only (no liability or rate determination). It does not describe the response shape or whether guidance can be stale by jurisdiction.

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

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

Two tight sentences: the first front-loads what the tool returns and for whom, the second gives timing and the scope exclusion. 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 optional parameter, read-only tool with no output schema, the description covers what it returns, when to call it, jurisdiction coverage, and its limits. Only the returned guidance format/details are left implicit, which is acceptable given the lack of an output schema.

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

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

Schema coverage is 0% and the schema merely constrains the field to a two-letter uppercase pattern. The description compensates by enumerating the accepted values (US, CA, GB, AU) and implying the country is optional by offering a general checklist, which the schema's zero required parameters corroborates.

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 concrete verb and resource ('Read dated official-source tax setup guidance') plus the exact jurisdictions covered (US, CA, GB, AU) and a no-country checklist variant. An agent can distinguish it from the sibling tax_profile_set, which writes setup rather than reading guidance.

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 timing triggers: 'before tax setup' and 'whenever jurisdiction or service changes.' It also bounds scope with 'does not determine liability or a rate.' It does not explicitly name the alternative sibling (tax_profile_set) for actually persisting setup, so it stops short of full routing 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds that values must be 'confirmed' and clarifies the unknown/not_registered distinction, which is real value. It never says whether an existing profile is replaced wholesale or merged, which matters for a destructive, idempotent setter.

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, with the ownership/confirmation constraint front-loaded before the prerequisite and the enum caveat. Every clause carries information an agent needs.

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

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

The tool takes a nested profile object with required reviewed_on and notes plus up to 20 registrations, and it is marked destructive, yet the description says nothing about replacement semantics or what a valid reviewed_on means. With no output schema and only annotations for the safety profile, this is adequate but leaves real gaps for a write tool of this 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?

Schema coverage is 67% and the two top-level parameters carry their own descriptions, including the retry rule for request_id and when to omit business_id. The description names the profile fields in prose but adds nothing about registration_status values, reviewed_on, notes, or the 20-item cap on registrations. Baseline 3 given the schema already does most of the work.

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?

Uses a specific verb (record) with the resource fields it captures: country, region, registrations, effective dates. It also signals the boundary versus tax_guide by making that tool a prerequisite, so an agent can tell the two apart. It stops short of naming itself as the write counterpart to a read tool, but the intent is 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?

'Read tax_guide first' gives an explicit ordering constraint, and 'unknown is not the same as not registered' gives a semantic rule that changes how the enum should be filled. There is no explicit when-not-to-call or stated alternative for correcting an existing profile, so it is clear context rather than complete routing 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, idempotentHint and destructiveHint=false, so safety is fully covered by structured data. The description adds only one behavioral detail (running timers return elapsed minutes); it says nothing about pagination, default result size, or what filtered results look like.

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

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

Two short sentences with no filler, and the listing scope is front-loaded. The phrasing 'running ones with their elapsed minutes' is slightly clipped but readable.

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?

A five-parameter list tool with no output schema and 20% schema coverage needs the description to explain filtering, pagination, and return shape. The description covers none of these, leaving significant gaps for correct invocation.

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

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

Schema description coverage is only 20% — just business_id is documented. The description adds no meaning for limit, offset, state, or client_id, so an agent gets no guidance on the four undocumented 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?

States a specific verb+resource ('List timers') and adds scope detail that running timers include elapsed minutes. It is clearly distinct from timer_start/timer_stop, though it never names those siblings explicitly.

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?

'Check for running timers before starting another for the same work' gives a concrete use condition tied to timer_start. It stops short of stating exclusions or naming the alternative tool explicitly.

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 real behavioral context beyond the annotations: multiple concurrent timers are allowed, and the server clock is the default start time. However, annotations declare destructiveHint=true and idempotentHint=true, and the description never explains why starting a timer is destructive or how retries interact with request_id, leaving the most consequential hint unexplained.

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

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

Three short sentences with zero waste, and the trigger condition is front-loaded ahead of the timestamp and concurrency details.

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

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

For a five-parameter mutation with no output schema, the description covers the trigger, default time source, and concurrency but omits the unexplained destructive flag and the required description parameter. An agent could call it correctly but would be guessing on those two points.

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 60%, with request_id, started_at and business_id documented; client_id and description are not. The description reinforces client_id ('for work on a client') and started_at semantics, but says nothing about the required free-text description parameter, so it only partly compensates for the coverage gap.

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

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

States a specific verb and resource ('Start a timer for work on a client') with scope detail, so an agent can distinguish it from timer_stop and timers_list without opening the schema. It stops short of naming the sibling tools explicitly, so sibling differentiation is implicit rather than stated.

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 trigger ('when the user says they are starting') and a rule for the optional timestamp ('Otis's clock sets the start unless the user reports an earlier time'). It does not say when not to use it or point at an alternative such as timers_list or timer_stop.

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 description adds real context beyond them: the return payload (minutes and hours, exact to the minute), that rate_minor converts tracked time into billable work, that an already-stopped timer can be recorded by re-calling with a rate, and that discard records nothing. It does not explain the request_id idempotency contract, which is left to 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?

Four tight sentences, front-loaded with the trigger and outcome, then the two conditional behaviors. Only the trailing "discard throws a timer away" feels tacked on, but it is still load-bearing 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 6-parameter mutation tool with no output schema, the description covers the return value, the billable-recording path, and the destructive discard path. The remaining gaps (stopped_at backdating, business_id scoping, request_id retry semantics) are all handled by the schema and annotations.

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 83%, so the schema already documents discard, rate_minor, stopped_at, business_id and request_id thoroughly. The description reinforces the rate_minor workflow (re-call to bill an already stopped timer) and discard semantics, but those points are largely mirrored in the schema descriptions, so it adds limited marginal meaning.

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

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

The description opens with a specific verb+resource ("Stop a timer") and is clearly distinct from the timer_start/timers_list siblings. It goes further by naming two behavioral branches (billable recording via rate_minor, and discard). It stops short of explicitly routing to siblings, so a 4 rather than a 5.

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?

"Stop a timer when the user says they stopped" gives a concrete trigger, and the rate_minor sentence supplies a real decision rule (ask for the rate and call again if none was supplied). The discard clause identifies the alternative path for throwing a timer away. No explicit when-not-to-use exclusions, so not a 5.

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