MTD Chase — chase clients for MTD records

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false), so the description carries real weight and does: it discloses the dry-run default, what the preview reports (would-add, duplicates skipped, rejected, plan-limit effect), the 500 cap, and that confirm:true persists. It stops short of stating partial-failure behavior or required permissions, so it is strong but not exhaustive.

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

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

Three compact blocks — behavior, when-to-use, when-not-to-use — with the dry-run semantics front-loaded in the first sentence. No filler, and the labeled structure makes scanning trivial.

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 batch mutation with no output schema, the description covers the critical unknowns: default is non-destructive preview, what the preview reports, the size cap, and the dedupe rule. What the saved response returns (e.g. created/skipped counts) is not described, a minor gap given no output schema exists.

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 description compensates for the gaps that matter: it explains confirm's dry-run/save split and the 500-item ceiling, and clarifies the matching keys (email, then exact name) that govern duplicate handling. Nested item fields like ref, tags, and mobile are left to the schema, which is acceptable since they are self-evident.

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 (Adds) and resource (Clients), defines the domain term inline ("people the practice does MTD quarterly updates for"), and specifies the input form (pasted list) plus the dedupe rule (email, else exact name). An agent can distinguish this from update_client without opening either schema.

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

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

Explicit "Use this when" names the concrete scenarios (spreadsheet, accounting-software export, typed list), and "Not for: changing one Client (update_client)" names the sibling alternative and the condition that selects 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 annotations, it discloses concrete side effects: open Chases become skipped, links stop working, and the Client stops counting toward the plan limit. It also explains the critical dry-run default (confirm:false shows what would change) and reversibility via unarchive, which the destructiveHint alone would not convey.

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

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

Two compact sentences front-load the effect of the action, then the usage condition. Every clause carries new information (consequences, dry-run default, reversal) with no repetition beyond the necessary restatement of confirm.

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 mutation with annotations already covering the safety profile and no output schema, the description supplies consequences, precondition, and the reversal path. It omits retry guidance for idempotency_key even though idempotentHint is false, which is the only meaningful 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 coverage is 75%, and the one undocumented parameter, unarchive, is fully explained in the description ('brings them back'). The confirm semantics are restated with the same meaning as the schema, and idempotency_key is left entirely to the schema, so it adds value but not across all four parameters.

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

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

The description names a specific verb and resource (archive a Client) and its inverse (unarchive:true), and describes the resulting state change. It is clearly distinguishable from siblings like update_client or list_clients, which act on data rather than lifecycle status.

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

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

It gives an explicit trigger: 'Use this when: a Client leaves the practice or comes back.' That covers both directions of use. It does not, however, name an alternative (e.g., update_client for correcting details instead of removing access), so routing is clear by context rather than by explicit exclusion.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the exact breadth of data included and the delivery mechanism (a download link scoped to the signed-in practitioner), which no annotation conveys. It does not mention latency, size limits, or whether generation is synchronous, which keeps it from a 5.

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

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

Two sentences, zero filler: the first front-loads what is exported and what is returned, the second front-loads the trigger condition. The parenthetical enumeration is dense but every item adds distinguishing scope.

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, the description carries the burden of explaining the return value, and it does so ("one JSON file; returns a download link for the signed-in practitioner"). Combined with the full data inventory and the auth scoping, an agent has everything needed to select and call this tool correctly.

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

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

The tool takes zero parameters, so there is no schema semantics for the description to compensate for; the baseline for a parameterless tool is 4. The description correctly implies no input is required and instead spends its words on scope and output.

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 ("Exports") and an explicit, enumerated scope: Clients, Chases with history, Nudges sent, Records list, requests. It also names the output artifact (one JSON file with a download link), so an agent can immediately distinguish this bulk export from siblings like list_clients or list_records that return subsets.

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 an explicit trigger condition ("Use this when: they want a copy of their data or are leaving"), which gives a clear situational context. It stops short of naming an alternative tool or stating when not to use it, so it falls just below the full when/when-not/alternatives bar.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the output includes a ready-to-paste message, which signals the practitioner must deliver it manually — useful, but nothing is said about per-client failures (unknown names), ordering, or whether links expire.

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 zero redundancy: the first states what is returned, the second front-loads the selection condition. Nothing could be removed without losing 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?

No output schema exists, so the description carries the burden of explaining returns, and it does so by naming both returned artifacts (link and paste-ready message). With only two fully documented optional parameters, the remaining gap is minor edge-case behavior rather than anything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters document their defaults (all clients being chased; the Quarter whose HMRC deadline is next), so the baseline is 3. The description's mention of 'a Quarter' and 'each Client' merely echoes the schema without adding format examples or override behavior.

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 and scope: per-Client personal records link for a Quarter, plus a pre-written message. That is clearly distinct from the sending tools among the siblings (send_nudges_now, mark_chase), though it never names a sibling explicitly to draw the contrast.

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 'Use this when' clause gives concrete selecting conditions: no email on file, or the practitioner prefers a messaging app or text. This effectively implies the alternative (automated sending) without naming it, so the routing is clear but requires one small 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so safety is covered structurally. The description adds non-obvious behavior the annotations cannot convey: omitting the client parameter changes the result set entirely into a lateness ranking across all active Clients, and each result carries a one-line summary. It stops short of noting result volume, ranking method, or ordering of the per-quarter entries, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the core return content, then labeled 'Use this when' and 'Not for' sections that scan instantly. No filler or restatement of the name; the dash-separated clause packs the measurement detail without bloat.

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

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

There is no output schema, so the description must carry return-value semantics, and it does: quarter-by-quarter chase outcomes, lateness magnitude and direction relative to the requested date, an HMRC-deadline flag, and a summary line. Combined with a fully documented single parameter and complete annotations, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100% and the single parameter is documented (name, email, or own reference), so baseline is 3. The description earns above baseline by explaining the semantic consequence of the optional parameter being absent — the call pivots from per-client history to a cross-client lateness ranking — which the schema alone cannot tell an agent.

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 the specific resource (a Client's Chases), the grouping axis (across Quarters), the exact measures returned (days early or late vs. the requested date, and vs. the HMRC deadline) plus a one-line summary. It also states the no-argument fallback behavior (every active Client ranked by usual lateness), which no sibling name implies, so an agent can distinguish it from whos_outstanding and list_clients without reading 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 routing is given: 'Use this when: asked whether a Client is usually late, how they did last time, or who's always late.' A negative case is also stated — 'Not for: who hasn't sent records this Quarter (whos_outstanding)' — naming the exact sibling to prefer instead. Both the when and the 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 already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the 'Works without signing in' auth condition, which an agent needs to know before choosing this tool for an unauthenticated flow. It stops short of describing pagination or caching, but neither is relevant for a fixed four-period result.

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 padding: what it returns first, then when to use it, then the exclusion. The structure is front-loaded and the labeled 'Use this when' / 'Not for' pattern is easy to scan.

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 and does so by enumerating periods, deadlines, final declaration date, and days-until-next-deadline. Combined with the single optional parameter and fully covered annotations, an agent has everything it needs 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% and the single parameter is fully documented in the schema, including the example format "2026-27" and the default of the current tax year. The description only says 'for a tax year' without adding format or default 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 ('Returns') and a precisely scoped resource: the four MTD for Income Tax quarterly update periods for a tax year, plus deadlines, final declaration date, and days remaining. The parenthetical '(standard and calendar period ends)' distinguishes the two period conventions, so the agent knows exactly what comes back.

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?

Has an explicit 'Use this when' clause covering both the deadline question and the 'what a Quarter covers' question, and a 'Not for' clause that names the correct sibling (whos_outstanding) for the adjacent record-tracking question. This is the strongest possible 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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the shape of the result (limits, counts, unset settings, suggested phrases) even though no output schema exists; it stops short of saying what happens when no plan is configured.

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

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

Two sentences, front-loaded with the return payload, followed by a single conditional usage line. Every clause carries information and nothing is repeated from the annotations or schema.

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

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

With zero parameters and no output schema, the description carries the burden of describing the result, and it does so thoroughly for a read-only status tool. The only soft spot is the vague phrase 'the next few things the practitioner can say', which leaves the format of that portion unclear.

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 and the baseline is 4. The description correctly implies no arguments are needed by framing it as a status read.

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

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

The description names a specific verb (Returns) and enumerates exactly what is returned: plan and active Clients vs limit, open Chases per Quarter, unset settings, and suggested next phrases. That enumeration clearly separates it from siblings like list_clients or whos_outstanding, which return single resource types rather than a consolidated status.

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

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

It gives an explicit trigger: 'Use this when: the practitioner asks where they're up to or what to do next.' That is a clear usage context, but it does not name alternatives (e.g. whos_outstanding for outstanding items only) or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description usefully adds what the payload contains (contact details, period type, tags, Quarter Chase status), but says nothing about pagination, result limits, ordering, or how archived clients are treated.

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 with the returned fields front-loaded and the usage scenarios second. Nothing is repeated from the annotations or the schema, though the "Use this when:" fragment list reads slightly clipped.

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

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

For a simple read-only list tool with no output schema and no required parameters, the description does the important work of naming the returned fields and the use cases. The remaining gap is volume/ordering behavior on a potentially large client list, which an agent calling it would want to know.

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%, with just the "text" parameter documented as "part of a name or email". The description partially compensates by giving tag semantics through an example ("a tagged group (e.g. landlords)"), but it never explains include_archived, the standard vs calendar period_type filter, or the matching behavior of tag.

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

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

The description opens with a specific verb and resource ("Lists Clients") and enumerates the payload: contact details, period type, tags, and current-Quarter Chase status. It does not explicitly distinguish itself from close siblings like whos_outstanding, list_records, or get_client_history, so differentiation is left to inference.

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 "Use this when" clause gives three concrete scenarios: roster lookup, retrieving a Client's details, and viewing a tagged group with Quarter status. It is clear context but offers no when-not guidance or named alternative (e.g., use whos_outstanding for chase-only views).

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description is not required to restate them. It adds real value by disclosing what each row contains — status taxonomy, request frequency, workaround text, decline rationale — which tells the agent this is a rich per-item read rather than a bare list. It does not mention ordering, scoping to the caller's practice, or whether declined entries remain visible long-term, which keeps it from a 5.

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

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

Three short blocks — what it returns, when to use, when not to — front-loaded with the payload description. No filler, no restatement of the title, and the sibling routing is packed into a single terse clause.

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

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

With zero parameters and no output schema, the description carries the entire burden of explaining return content, and it does so field by field, including the meaning of each status value. An agent can decide to call it and describe its result without opening anything else.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add meaning to. The description correctly avoids inventing options the schema does not support, implying a fixed, unpaginated full 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?

Specific verb (lists) plus resource (the practice's feature requests) and an explicit enumeration of the payload: status values (open, planned, live, declined), ask count, workaround, and decline reason. That enumeration alone lets an agent distinguish this from every sibling in the 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?

Provides an explicit trigger condition ("asked what happened to something they asked for") and two named exclusions with the correct alternatives: request_feature for new asks and whats_new for recently shipped items. Both the when and the 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior — download links expire after 24 hours and are scoped to the signed-in practitioner, and the Client's note is attributed to the Client — which is real value beyond the annotations. It stops short of covering result ordering or volume limits.

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

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

Two sentences, front-loaded with what is returned, then the usage trigger. Dense but every clause carries information (returned fields, link lifetime, aggregation scope, note attribution). The opening sentence is long and stacks several facts, but none are 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 compensates by naming the returned fields and the link expiry. For a two-parameter, zero-required read tool with full annotation coverage, an agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns more by explaining the omission semantics: supplying no client means every Client in the Quarter, and the quarter scope defines the window. That meaning is only implicit in the schema, where both parameters are optional with no statement of what omitting client does.

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

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

The description opens with a specific verb and resource — 'Lists the files (name, size, received) a Client sent through their link for a Quarter' — and even previews the returned fields. It is clearly distinct from list_clients or get_client_history in substance, though it never names an alternative to steer the agent 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?

'Use this when: asked what a Client sent or to download it' gives a concrete triggering condition, and the 'or for every Client in a Quarter' clause hints at the aggregate case. There is no explicit when-not guidance or named alternative tool, keeping it below 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 cover readOnlyHint=false and idempotentHint=true, but the description adds non-obvious consequences the annotations cannot express: nudges stop for ready/nothing_to_report/skipped and resume for waiting/partial, and the change is written to the Client's history. Those side effects are exactly the kind of behavioral context an agent needs before mutating chase state.

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

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

The core behavior and its nudge side effects are front-loaded in the first sentence, with the usage trigger isolated on its own line. The first sentence is dense but every clause carries information; nothing is padding.

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

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

For a 6-parameter mutation with no output schema, the description covers the state space, the nudge consequences, history recording, and when to invoke it. It does not say what happens on an unknown client or what a successful response contains, but the essential calling information is present.

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

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

Schema description coverage is 67%, so the schema already documents client, quarter, recount, and idempotency_key. The description only restates the status enum and mentions the optional note, adding no new meaning for recount or the idempotency key beyond what the schema supplies, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Sets one Client's Chase for a Quarter') and enumerates the exact target states (ready, partial, nothing_to_report, skipped, waiting). Combined with the 'Use this when' clause about records arriving by other routes, it is distinguishable from siblings like start_chase or send_nudges_now 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?

It gives an explicit 'Use this when:' trigger with two concrete conditions (records arrived another way; a Client should be skipped this Quarter), which is real routing guidance rather than implied usage. It stops short of naming an alternative tool or stating when-not to use it (e.g. versus start_chase).

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, idempotentHint=true and destructiveHint=false, so safety is largely covered; the description adds the valuable detail that the result warns if the pause extends past a deadline, and that the change is reversible via resume. It does not explain permission requirements or what happens to a queued nudge already in flight, 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 lines: behavior first, then when-to-use, then when-not-to-use. No filler, and the most decision-relevant fact (what it stops and how to undo it) is front-loaded.

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

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

With no output schema, the description compensates by noting the deadline warning in the result, and it covers both pause and resume paths for a 4-parameter mutation tool. Minor gaps remain around permissions and the effect on already-scheduled nudges, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 75% and the YYYY-MM-DD format is already in the schema, but the description supplies the meaning of resume:true (restarts the nudges), which the schema leaves as an undescribed boolean with a default. That is genuine added semantics beyond the structured fields, though 'until' and idempotency_key get no extra depth.

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 ('Stops all Nudges to one Client') plus the two modes: a dated pause and a resume via resume:true. It also names the boundaries against siblings (archive_client, mark_chase), so an agent can distinguish it from set_nudge_plan or send_nudges_now 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 an explicit 'Use this when' trigger (client ill, away, or asked for no reminders) and an explicit 'Not for' with the correct alternatives for each exclusion. This is the when/when-not/alternatives pattern at full strength.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond them: it deduplicates against open requests by adding a vote, it states what is returned, and it sets the expectation that "No date is promised." It does not say what happens on retry beyond the schema's idempotency key, and the vote-matching/merge behavior could use one more sentence.

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 action and return value, then a clean when/not-for block. The opening clause about "asking for something none of the other tools can do" is nearly repeated by the "Use this when" line, a small redundancy, but no sentence is wasted overall.

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 write tool with no output schema, the description supplies the return shape, the no-commitment-on-timing caveat, and the routing rule. Remaining gaps are minor: no failure/error behavior and no guidance for the optional `closest_existing_tool` field.

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 baseline is 3, and the description adds little per-parameter meaning beyond the vote-matching hint. The undocumented `closest_existing_tool` parameter in particular is left without guidance in prose, which is exactly the field an agent would fill inconsistently.

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 ("Files a request with MTD Chase") and immediately delimits it against all siblings: it is for capabilities "none of the other tools can do." It also covers the second mode ("adds a vote to a matching open request") and the return payload (ID, status, workaround), so an agent can place it precisely among the 19 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?

Gives an explicit positive trigger ("Use this when: the practitioner wants a capability MTD Chase doesn't have") and an explicit exclusion ("Not for: reporting a single Client's problem"), which is the split an agent would otherwise get wrong versus client-level tools. It also names the alternative path implicitly by routing unmatched capabilities here instead of to another 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?

Adds substantial behavior beyond the annotations: a hard at-most-one-per-Client-per-day cap, a dry-run default that changes nothing, and the exact exclusion reasons reported (no email, nudged today, paused). It does not explain retry/idempotency behavior even though idempotency_key exists and idempotentHint is false, leaving a real gap for a non-idempotent send action.

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 paragraphs: the first front-loads what happens and the rate limit, the second front-loads when to use it. Every sentence carries information and nothing is padded.

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

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

For a write tool with no output schema, the description covers who is targeted, the daily cap, the dry-run/send split and exclusion reporting, which is nearly everything needed to call it safely. It could still say what the dry-run result actually looks like and how retries interact with idempotency_key.

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 all five parameters are already documented in the schema, and the description largely restates confirm and clients defaults. It does add meaning by specifying that the dry run enumerates who would be emailed and who is excluded and why, but quarter, only_status and idempotency_key get no extra explanation.

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 (sends a Nudge email now) plus its precise target population (Clients who haven't finished sending records for a Quarter, waiting or partial). This clearly separates it from plan-based siblings like set_nudge_plan and set_nudges/pause_nudges.

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 frames the when: chasing up everyone outstanding or named Clients, now, as an extra reminder outside the plan. The 'outside the plan' phrasing implicitly contrasts with set_nudge_plan, but no sibling tool is named outright and there is no explicit when-not guidance (e.g. when to prefer the plan or pause_nudges).

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, destructive=false, idempotent=true, openWorld=false. The description adds real context beyond that: the change applies retroactively to already-running Chases, sends occur at 09:00 UK time on weekdays only, omitted values retain their current setting (partial update), and the return value is a prose plan plus this Quarter's remaining nudge dates.

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 return value, then a clean 'Use this when / Not for' block. The opening sentence is long and clause-heavy with parentheticals, but every part carries information the 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?

For a mutating 4-parameter tool with no output schema and no required parameters, the description covers scope, timing, partial-update behavior, return shape, and sibling routing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still earns extra credit by explaining that day offsets are counted from the ask-by date and that a left-out value keeps its current setting, which is partial-update semantics the schema does not state.

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 (sets when nudge reminder emails go out), the scope (every Chase, including ones already running), and the reference point (the ask-by date). This is clearly distinguishable from send_nudges_now, pause_nudges, and update_practice 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?

Explicit 'Use this when: the practitioner wants reminders on different days' plus a 'Not for' clause naming three sibling alternatives and the condition each covers (one extra reminder now, one Client, the ask-by date itself). 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?

Beyond annotations (which only say non-read-only, open-world, non-destructive), it discloses the actual side effects — personal links are minted, a first email plus a series of Nudges on the practice's nudge plan are sent — and describes the dry-run preview in concrete terms (who would be chased, who has no email, checklist, send-by date, HMRC deadline). It also explains the repeat-safety semantics ('Clients already being chased are left alone'), which usefully qualifies the idempotentHint=false annotation by clarifying that duplicates are avoided at the client level rather than the call level.

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

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

Front-loaded with the core action and then cleanly sectioned with 'Use this when' and 'Not for' labels; nearly every sentence carries information. The opening sentence is long and packs the email/Nudge sequencing into one breath, and the parenthetical explaining the two preview dates is slightly dense, costing a point.

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?

Rich enough for a mutating, open-world tool with no output schema: it covers side effects, the dry-run preview, the default quarter, and repeat-safety. It stops short of saying what confirm:true returns (job id, counts) or how the existing nudge plan affects timing, which an agent inspecting results might want.

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 already 100%, so the baseline is 3; the description earns above that by adding meaning to `confirm` beyond the schema's generic 'shows what would happen' — it names the four things the preview returns. The targeting and checklist parameters and the default quarter are covered, though the idempotency_key parameter is left to the schema.

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

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

The description states a specific verb and resource ('Starts chasing Clients for their records for a Quarter') and goes on to name the exact mechanics: a personal no-login link, a first email, then Nudges on the practice's plan. It is clearly distinguishable from the closest sibling, send_nudges_now, which is explicitly excluded.

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 has an explicit 'Use this when' block that enumerates the three targeting modes (everyone, a tag group, one Client) and the checklist variant, plus a 'Not for' block naming the alternative for reminders and the unrelated case. There is no ambiguity about when to reach for this tool versus a sibling.

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, idempotentHint=true and destructiveHint=false, so safety is covered; the description still adds value by stating 'Returns before → after', telling the agent the response is a diff. It stops short of clarifying partial-update semantics (whether omitted fields are left untouched) or whether a failed match errors, which are meaningful for a mutation tool.

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

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

Three short lines: purpose plus return shape, then when-to-use, then when-not-to-use. Front-loaded and every clause carries routing or behavioral information; nothing is padding.

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

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

For an 8-parameter mutation with no output schema, the description covers the intent, the mutable field set, the return shape and the sibling boundaries. The gap is that partial-vs-full replacement semantics and target identification via 'client' versus 'ref' remain unstated, which an agent would want before 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 description coverage is only 25%, but the description compensates by naming six of the eight parameters (name, email, mobile, period type with both enum values, tags, reference) as the updatable fields. The one residual ambiguity is whether 'ref' supplies a new reference value or identifies the client alongside 'client', which the text does not resolve.

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 a specific verb (changes) and resource (one Client) and enumerates the mutable fields, including the period_type enum values. It also explicitly separates itself from archive_client and pause_nudges, so an agent can pick it over siblings without reading 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 'Use this when: a Client's details change' plus a 'Not for' line routing the agent to archive_client and pause_nudges for those adjacent intents. Both the affirmative and negative conditions are stated, 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 the write, idempotent, and non-destructive profile, and the description adds genuinely new behavioural context: the ask-by change applies only to Chases started afterwards, running Chases keep their existing checklist, and the tool returns a before → after diff. The main gap is that it never states the partial-update contract (omitted fields unchanged) or any permission requirement.

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?

Content is dense and front-loaded, with the effect surface first and a separate 'Use this when:' sentence for routing; every clause carries information. The drawback is presentation: eight field behaviours are packed into one very long run-on sentence, which is harder to scan than a short list.

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 9-parameter, zero-required mutation tool with no output schema, the description covers most of what an agent needs, including a hint at the return value ('before → after') and the forward-looking scope of changes. It is not fully complete: partial-update semantics and validation-failure behaviour are unstated, which matters when all parameters are optional.

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 56% schema description coverage, the description does real work: it explains that name and phone are Client-visible, that phone can be cleared, the 0–30 range with default 10 for ask_by_days, the 30–365 range for retention_days, and the 1–8 item limit for default_checklist. It does not clarify the semantics of sign_off, reply_to_email, or daily_summary beyond naming them, and leaves idempotency to the schema.

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

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

The description opens with a specific verb ('Changes') and then enumerates the exact resources and behaviours affected: client-visible name, reply-to email, sign-off, phone, ask-by days, retention days, daily summary, and default checklist. An agent can distinguish this from update_client (single client) and set_nudge_plan (nudges) 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?

The explicit 'Use this when:' clause gives concrete triggers (practitioner changes their details, the send-by date, default checklist, or retention), which is stronger than implied usage. It stops short of naming exclusions or alternatives, e.g. that per-client changes belong to update_client or nudge cadence to set_nudge_plan.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds useful behavioral detail about response content (go-live dates plus how to try a change). It does not say how far back "recently" reaches, whether results are ordered or capped, or how empty states appear, which leaves real gaps for a no-parameter listing 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?

Two sentences, front-loaded with the capability and followed by the triggering intent. Every clause carries information; the phrase about the date and what to say to try it directly describes the output, so 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?

With no parameters, no output schema, and annotations already covering safety, the description needs only to explain what comes back and when to call it — and it does both. The only omission is the scope of "recently" and result ordering/cap, which an agent cannot infer.

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 and the baseline of 4 applies. The schema is empty and fully consistent with the description's implication that the call needs no arguments.

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 ("Lists") with two concrete resources: recent changes live in MTD Chase and which of this practice's requests have gone live. It also previews the returned content (date, what to say to try it). It stops short of naming a sibling such as list_my_requests or request_feature, so the boundary between those tools is only implied.

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 this when: the practitioner asks what's new, or whether something they asked for is live yet" gives an explicit triggering condition tied to user intent. There are no when-not-to-use notes or named alternatives, but the trigger is clear enough to route the call confidently.

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 that this is a read-only, non-destructive, idempotent, closed-world operation. The description adds meaningful behavioral context beyond that: it explains which statuses are included (waiting or partial) and which derived fields are returned (days to/after the requested date, last Nudge, link-open status, status counts), though it does not describe ordering or response shape in detail.

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

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

The definition is three compact sentences with zero wasted wording. Purpose is front-loaded, usage triggers follow, and the exclusion appears last, making it easy to scan.

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 reporting tool with complete schema coverage and annotations covering safety, the description supplies enough context to call it correctly. Since there is no output schema, it helpfully names the returned fields, but it stops short of describing the exact response structure or ordering.

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 both parameters are already documented: quarter format/default and the late_last_quarter filter. The description does not add additional meaning about parameter behavior beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: returns Clients who haven't finished sending records for a Quarter, including waiting/partial statuses. It also distinguishes itself from list_clients with a tag, so an agent can select it without confusion.

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 when-to-use triggers (who's still outstanding, who's sent what, how the Quarter is going) and an explicit not-for case pointing to list_clients with tag. This is clear routing guidance with no inference required.

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