SHVL

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closedWorld, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: nothing is stored, no messages are sent, the drafts are review-only, and the calculations are indicative rather than legally binding.

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 verb and the input requirement, then a second sentence carrying the non-storage/no-send behavioral disclosure. Dense but every clause contributes; 'UK B2B chase wording' is jargon but precise enough to be useful.

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?

An output schema exists, so return values need not be explained, and annotations plus full schema coverage carry most of the remaining burden. What is missing is only marginal: how malformed CSV or unparseable dates are handled, and that the 50-row cap is a hard limit.

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

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

Schema description coverage is 100%, so all five parameters (including as_of_date, draft_stage and the 50-row cap) are already documented in the schema. The description only restates that the CSV and Bank Rate are 'user-supplied', adding no format or edge-case detail, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Analyse a user-supplied aged-debtors CSV') and names the concrete outputs (chase wording, statutory-interest and fixed-compensation calculations). It is clearly distinguishable by the 'analyse' verb and CSV input from the get_* siblings, though it never explicitly contrasts itself with them.

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

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

Usage is implied through the required inputs (caller must supply CSV text and a Bank Rate) and the 'review-only' framing, which tells the agent the output is not sent anywhere. There is no explicit when-to-use/when-not-to-use statement or routing to get_credit_control_brief or get_receivables_health for the non-CSV path.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety bar is low. The description still adds real value by naming the data source ('latest SHVL import or completed accounting sync') and stating 'never sends a reminder', which pre-empts the most likely misread of a payment-reminder tool.

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

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

Three sentences, front-loaded with the trigger and with zero filler, which is well structured. It is on the shorter side for a tool with a freshness caveat, so the tightness slightly trades off completeness.

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

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

With an output schema present, return values need not be explained, and the description covers scope, data freshness and the read-only guarantee. Only edge behavior — such as what returns when no import or sync has completed — is unaddressed.

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, including the limit maximum of 5 and the workspace_id sourcing rule. The description reinforces the cap ('up to five customers') and frames results as priority cases, but adds no syntax or sourcing detail beyond the schema.

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

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

The description opens with a concrete verb and resource: return overdue totals plus up to five customers to check first. That is specific enough to separate it from get_receivables_health and analyse_aged_debtors_csv, though it never names a sibling to distinguish itself 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?

It gives clear trigger phrasing ('Use when someone asks who owes money, which invoices are overdue or which customers need a payment reminder'), which is stronger than most definitions. It stops short of naming which sibling to prefer for narrower questions like a single case or an aged-debtor CSV.

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 real value beyond that with an explicit exclusion list (email addresses, message content, provider IDs, payment records) and the 'bounded' qualifier on invoice summaries, telling the agent what it will not get back.

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 returned, the second states the privacy boundary. 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?

An output schema exists, so the description need not explain return shape, and it still summarizes payload sections plus the exclusion boundary. For a two-parameter read tool with full annotation and schema coverage this is nearly complete; only explicit sibling routing is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the 'never infer a different client workspace' warning. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Return one case') plus the resource and scope ('from the signed-in SHVL workspace'), and enumerates the payload contents (status, payment-readiness state, invoice summaries, communication evidence). This clearly separates it from sibling list/search tools like search_credit_control_cases.

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 singular 'one case' plus the required case_id imply retrieval-by-identifier rather than search, but the description never explicitly says when to use this instead of search_credit_control_cases or get_credit_control_brief. No exclusions or prerequisites are stated in the description text (the workspace_id schema hint carries the selection constraint).

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, non-destructive and closed-world, so the safety profile is covered. The description adds beyond that: the view is scoped to the signed-in workspace, and the qualifier 'where available' warns that some metrics (concentration, 30-day movement) may be absent, which prepares the agent for partial results.

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, both load-bearing: the first front-loads what is returned, the second front-loads the exclusions. No filler, no restatement of the title, and the negative scope is placed where an agent scanning for routing cues will hit it.

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

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

With an output schema present, the description needn't explain return shapes, and it doesn't waste effort there. For a single-parameter read tool the definition is essentially complete; the only mild gap is that availability of certain metrics is hedged with 'where available' without saying how the agent should react when they are absent.

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

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

Schema coverage is 100% and the single workspace_id parameter already carries a strong description telling the agent to use the exact id from list_shvl_workspaces and never infer a workspace. The tool description only echoes the signed-in-workspace scoping, adding no syntax or format detail beyond the schema, 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 opens with a specific verb and resource ('Return a read-only receivables health view') and then enumerates the exact contents: AR balance, overdue ageing, invoices raised this month, payments recorded, concentration and 30-day overdue movement. It closes with explicit negative scope ('not a bank balance, cash-flow, profit or whole-business health report'), which sharply separates it from the credit-control and aged-debtors siblings.

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

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

The negative framing tells the agent when NOT to reach for this tool (cash-flow, profit, whole-business health questions), which is real routing guidance. It stops short of naming the specific alternative siblings (get_credit_control_brief, analyse_aged_debtors_csv) that would serve those adjacent questions, so the agent must still infer the redirect.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered and nothing here contradicts it. The description adds only that this is a status/entitlement read against a Xero-connected tenant, without disclosing whether entitlement state can be stale, what happens for a workspace with no connected org, or any auth prerequisites.

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

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

One sentence, front-loaded with the verb, with every clause naming a concrete returned field. No filler, no restatement of the title, and nothing that could be cut 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?

A simple read-only tool with one fully documented required parameter and an output schema that already explains the return shape, so the description does not need to spell out return values. Its only real omission is the sequencing relationship with list_shvl_workspaces, which would make the definition self-sufficient.

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

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

There is a single parameter with 100% schema description coverage, and the schema text already carries the important constraint ("Never infer a different client workspace"). The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ("Return") and resource (selected SHVL workspace status) and enumerates the exact fields surfaced: workspace name, entitlement state, connected accounting organisation, active Xero agent tenant. That distinguishes it from list_shvl_workspaces (enumeration) by implying a single already-selected workspace, but the 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?

The description contains no when-to-use or when-not-to-use guidance and names no alternative tool. The only routing hint ("selected") lives in the prose and the workspace_id schema text, not in an explicit instruction such as "call after list_shvl_workspaces once the user picks a workspace."

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 genuine context beyond that: results come from the most recent completed sync rather than live Xero data, the invoice payload is capped at 50, and email addresses, postal addresses and Xero IDs are deliberately excluded.

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

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

Two short sentences with zero filler; the scope and source are front-loaded and the exclusions follow immediately. 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?

An output schema exists, so return values need no explanation, and the description covers data freshness, the 50-invoice cap and field exclusions. It stops short of saying whether the cap truncates silently or how a missing or unsynced contact is signalled, which matters for a two-parameter lookup.

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

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

Schema coverage is 50%: workspace_id is well documented, customer_id has no schema description. The description partially compensates by implying customer_id is an internal customer identifier rather than a Xero ID (which it says are excluded), but it gives no format, provenance, or note on what happens for an unknown customer.

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 ('Return one customer contact summary and up to 50 sales invoices') and pins down the data source ('latest completed SHVL Xero sync'). It does not explicitly contrast itself with the sibling search_xero_contacts, though the singular-contact-plus-invoices scope implicitly separates it from the search tools.

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

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

Usage is only implied: an agent can infer this is the single-contact lookup keyed by customer_id, as opposed to searching. There is no explicit statement of when to prefer it over search_xero_contacts or get_xero_invoice, and no prerequisites beyond the workspace_id constraint already in the schema.

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 that already mark it read-only, idempotent, non-destructive, and closed-world, the description adds useful behavior: a hard cap of 250 stripped rows, no writes to Xero, and permission/Reports-access prerequisites. The term 'stripped' is not defined and truncation behavior beyond the cap is not explained, 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 tight sentences, front-loading purpose before limits and permissions, with no filler. The wording is compact and scannable.

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

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

It covers safety, access requirements, row cap, and report scope, and an output schema exists so return values need not be described. However, for a tool with five parameters and only 20% schema coverage, the unresolved meaning of date/from_date/to_date leaves a material invocation 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 20%: workspace_id is documented, but report, date, from_date, and to_date are not. The description names the three report types and says 'explicit dates,' yet does not explain whether date, from_date, and to_date are alternatives, how they interact, or which report types require which date fields.

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 ('Read'), a precise resource ('one live Xero Profit and Loss, Balance Sheet or Trial Balance'), and scope ('for explicit dates'). This clearly separates it from sibling contact, invoice, workspace, and credit-control tools without needing their schemas.

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

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

It implies use when a live financial statement is needed for explicit dates, but never explicitly states when to use this versus other reporting tools or when not to use it. No sibling alternative for financial reports is named, so the agent must infer the boundary from the resource name.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description matches with 'Read-only.' Beyond that it adds genuine context the annotations cannot: results are scoped to the latest completed sync (a staleness signal), payment data is aggregate rather than itemized, and named fields are excluded (Xero IDs, payment IDs, email addresses, message content). It does not describe pagination or error behavior, but for a single-record read that is minor.

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 sentences with the resource and scope front-loaded and the exclusions last. Every clause carries information: provenance, payment evidence, safety, redactions. No filler or repetition of the title.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description still covers provenance, aggregation level and redacted fields. The remaining hole is the invoice_id contract and whether the caller must resolve it via search_xero_invoices first, which an agent calling a two-parameter tool genuinely needs.

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

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

Schema coverage is 50% and only workspace_id carries documentation, which the description never reinforces or extends. invoice_id is undocumented in both places — the description never says what identifier it expects, how it is obtained, or how it relates to the excluded 'Xero IDs', leaving the most important input ambiguous. With half the parameters lacking meaning, the description should have compensated and does not.

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

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

The description uses a specific verb and resource ('Return one sales invoice') and pins the data source to the signed-in owner's latest completed SHVL Xero sync, with aggregate recorded-payment evidence called out. That singular framing implicitly contrasts with the plural sibling search_xero_invoices, but no sibling is named outright, so it stops short of a full 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?

Usage is only implied: 'one' invoice and the 'latest completed sync' scope suggest this is for fetching a known invoice rather than browsing. There is no explicit when-to-use, no statement that search_xero_invoices should be used to find an ID first, and no exclusion of cases (e.g. bills vs sales invoices) beyond 'sales 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious semantics: connecting an account does not create a workspace, and the response omits customer emails and provider identifiers. It does not discuss latency, caching, or ordering, but nothing material is missing for a zero-argument read.

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, front-loaded with what the tool returns, followed by the empty-state behavior and two clarifying negatives. Nothing is padded or repeated from 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?

An output schema exists, so return values need not be spelled out, yet the description still names the relevant empty-state fields (next_step, setup_url, summary_url) to guide follow-up. For a zero-argument, read-only listing tool this covers everything an agent needs to call it and act on the result.

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 no parameters, so the schema has nothing to document and the baseline is 4. The description correctly adds no pseudo-parameter detail, keeping semantics clean.

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

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

The first sentence gives a specific verb and resource ('List SHVL workspaces') plus the key scope constraint ('available to the signed-in user'), so an agent knows exactly what comes back. It does not explicitly distinguish itself from the other tools in the set (all of which are case/report tools), but the domain difference is clear enough from the resource name.

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

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

It gives concrete conditional guidance: if no workspaces exist, explain next_step and offer setup_url or the free summary_url. That is real when-to-use behavior an agent could not infer. It stops short of naming alternatives or saying explicitly when this tool should be called first in a flow (e.g., as a prerequisite to the credit-control tools).

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 covered; the description still adds the workspace scoping constraint and the 20-result cap, which an agent cannot derive from the annotations. Missing only whether results are ranked or paginated, which is minor given no pagination parameter exists.

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, with scope and search dimensions front-loaded before the read-only and result-cap qualifiers. Every clause carries information.

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

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

An output schema exists, so return shape needn't be described, and the annotations cover the safety profile. For a simple four-parameter search tool the description is nearly sufficient; only the status filter's purpose is left unexplained.

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 75%, so the schema already documents workspace_id and limit well; the description merely echoes the 20-result cap that limit's maximum already enforces. The status filter is never mentioned in the description, leaving the agent to discover the enum values 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 resource ('Search cases') plus the two searchable fields (customer name, invoice reference) and the scope ('the signed-in SHVL workspace'). This clearly separates it from get_credit_control_case, which fetches a single case, though the sibling is never named 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?

The phrase 'Search cases already held in the signed-in SHVL workspace' implies the use case is lookup-by-name-or-reference, and 'account-scoped' signals a prerequisite. There is no explicit when-not guidance or pointer to get_credit_control_case for retrieving one case by id, so the routing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real context beyond them: the data is limited to the latest completed sync (freshness), results are capped at 20 (completeness limit), and email, postal addresses and Xero IDs are stripped (a return-shape constraint). It does not say what happens on an empty or not-yet-synced case, but the added disclosure is substantial.

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

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

Two sentences with no filler, and the most important constraint (which sync the data comes from) is front-loaded before the result limitations. 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?

An output schema exists, so return values need no explanation, and the description still flags which fields are omitted. It also states the sync scope and cap. The only real omission is match semantics for query and behavior when no completed sync exists, which are minor for a read-only search.

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 33%, with just workspace_id documented, so the description must compensate for query and limit. It does partially: 'by name' explains query's meaning and 'capped at 20' explains the limit ceiling, but it never says whether the name match is exact or partial, nor what the default limit is. The workspace_id guidance lives entirely 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 resource ('Search customer contacts') plus a precise data scope ('signed-in owner's latest completed SHVL Xero sync') and the matching key ('by name'). It is clearly distinguishable from get_xero_contact and search_xero_invoices in practice, though it never names a sibling 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?

The 'by name' phrasing and the mention of only one sync imply this is a lookup-by-name entry point, but there is no explicit when-to-use or when-not guidance and no pointer telling the agent to fall back to get_xero_contact for full record detail. Usage is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, and closed-world behavior, so the bar is lower; the description still adds non-obvious traits: results are capped at 20 and reflect a stale sync snapshot rather than live Xero data. That staleness signal is the most valuable information an agent gets here. It leaves out ordering, pagination beyond the cap, and empty-result 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?

Two tight sentences with zero filler, and the scope and searchable fields are front-loaded before the read-only/staleness caveats. 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?

With a rich annotation set and an output schema present, the description only needs to carry scope, staleness, and cap, which it does. The missing piece is filter semantics for 'status' and how it interacts with 'query', a moderate gap for a four-parameter 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 25%, but the description compensates for the most important gap by defining what 'query' matches (invoice number or customer name) and reaffirming the 20-result cap on 'limit'. It says nothing about the 'status' enum filter or how it composes with the query, leaving one of four parameters entirely unexplained outside the schema.

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

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

The description gives a specific verb ('Search') and resource ('sales invoices') with the exact data source ('latest completed SHVL Xero sync') and searchable fields ('invoice number or customer name'). It distinguishes itself implicitly from the singular get_xero_invoice via 'Search', but never names or contrasts with a sibling 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?

It establishes a clear usage context: this queries synced data, not live Xero state, so an agent knows to avoid it when current-state accuracy matters. It does not, however, point to an alternative tool for live lookups or for browsing invoices without a query term.

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