AccountsOS

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

Beyond the annotations, the description discloses important side effects: bank statements are imported into a bank account that may be auto-created, and receipts or bills are read and matched. It also says the result reports what was found and what happened, giving the agent useful behavioral context for a write operation.

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

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

The description is front-loaded with the main action and is generally efficient. It includes some repetition of document types when explaining behavior, but every part remains useful and well structured.

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

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

For a non-idempotent write tool with a nested file object and no output schema, the description gives sufficient context about input expectations, side effects, and result shape. Minor gaps around duplicate handling or error behavior remain, but the core details an agent needs are 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 100%, so the parameters are already well documented. The description adds context about supported file types but does not add meaningful guidance beyond the schema for the company parameter or file object fields. Baseline 3 is appropriate.

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

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

The description begins with a specific verb and resource: 'Add a file ... to their AccountsOS books,' and clarifies the document types handled. This clearly separates it from read/search siblings, though it does not explicitly name or contrast with an alternative tool.

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

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

It provides a clear usage condition: 'Use it whenever the user attaches or mentions a financial document and wants it in their books.' It does not explicitly state when not to use it or name alternatives such as search_documents, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds meaningful context: it previews without locking, uses the same logic as the VAT page, and does not change anything. It could go slightly further by describing the response shape or whether figures are cached, but the behavioral profile is well covered.

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

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

The description is tightly written and front-loads the key distinction: preview without locking. Every sentence contributes to purpose, usage, or safety context, with no redundant restatement of the title 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?

There is no output schema, but the description explains that the tool returns a 9-box VAT breakdown derived from the period's transactions. Combined with the safety annotations, this is enough for an agent to call it correctly, though it does not detail the structure of the returned figures.

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 in the schema. The description does not add syntax or formatting details about period_id or company beyond what the schema provides, so the baseline 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?

States a specific verb and resource: previews a 9-box VAT breakdown for a period without locking it. It distinguishes itself from related tools like lock_vat_period and explains the calculation basis, so an agent can identify its role immediately.

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

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

Explicitly names when to use it, including example user phrases such as "what's my VAT for this quarter" and the pre-lock review workflow. It also positions it relative to lock_vat_period, leaving no ambiguity about when this preview tool is appropriate.

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, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: it hits a live external register and a 'not registered' response is a legitimate HMRC answer rather than an error — exactly the kind of detail that prevents an agent from retrying or reporting failure. It stops short of describing service-unavailable or rate-limit behavior, so not a 5.

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

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

Front-loaded with what it does and where the data comes from, then the caveat, then usage. Every sentence carries information, though the final sentence blends reporting instructions with description and could be marginally tighter.

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, yet the description states what comes back (registered trader name and address) and how to interpret a negative result. Combined with full schema coverage, an agent has everything needed to call it and act on the response.

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

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

Schema description coverage is 100%, so the schema already documents the 9-digit format, optional GB prefix, company selection, and contact_id purpose. The description adds only the GB-only constraint, which largely restates what the vat_number description implies. Baseline 3 is appropriate when the schema does all the parameter work.

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

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

States a specific verb (check), a precise resource (a UK VAT registration number), the authoritative source (HMRC's live Check-a-UK-VAT-number register), and the return content (registered trader name and address). The 'GB only' scope and the external-source framing make it clearly distinct from sibling tools like get_hmrc_vat_liabilities or get_vat_summary, which concern the account's own VAT position.

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?

Enumerates three concrete trigger scenarios (validity question, adding/editing a supplier or customer, confirming a VAT number on a document). It also tells the agent what to do with the result: report the registered name and flag a mismatch with the contact 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it is specifically for 'Deel EOR' (employer of record), which is useful context, but it does not disclose rate limits, external API dependencies, or whether the result is an estimate versus a binding quote. With annotations present, a 3 is appropriate.

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

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

The description is two concise sentences, front-loaded with the core action and followed by a clear usage example. Every sentence earns its place with no redundancy.

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

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

Given the rich annotations and full schema coverage, the description is largely complete for an agent to select and invoke the tool. It could be improved by explicitly contrasting with the take-home pay sibling, but the core information is sufficient.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the input schema. The description adds no additional parameter-level details (e.g., format hints or defaults). When schema coverage is this high, the baseline score is 3.

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 'Calculate' and resource 'total cost of hiring someone in a specific country through Deel EOR', making the purpose clear. It does not explicitly differentiate from the sibling tool 'deel_calculate_take_home_pay', but the distinction between employer cost and take-home pay is reasonably inferable.

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

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

It provides a clear usage trigger: 'Use when the user asks "how much would it cost to hire in [country]?" or about employment costs abroad.' This gives explicit context without exclusions. It does not mention alternative tools like deel_calculate_take_home_pay, which would be helpful for disambiguation.

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 openWorldHint, so the safety profile is covered. The description adds nothing behavioral beyond them — for a calculation tool it never says whether results are estimates, what tax year or assumptions apply, or how precise the output is, which is the context that actually matters here.

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 padding, with the core purpose front-loaded before the usage cue. Nothing to trim and nothing displaced.

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 should say what comes back (net amount only vs. a breakdown of deductions, currency of the result). It covers inputs adequately via the schema but leaves the return shape unspecified for an agent that must report the result to a user.

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%, including the useful note on the optional company parameter referencing list_companies. The description adds no meaning 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?

States a specific verb and resource (calculate take-home pay) plus the scoping inputs (salary, country). It does not distinguish itself from the closely related sibling deel_calculate_employment_cost, so an agent comparing the two gets no disambiguation.

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 trigger conditions are given: net pay, take-home salary, or deductions questions in a country. There is no guidance on when NOT to use it or how it differs from other Deel calculation tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description contributes only the content scope (contractor payment invoices); it says nothing about result volume, pagination, or default limit behavior. Adequate but not additive.

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

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

Two short sentences with the purpose front-loaded and no padding. The second sentence partially restates the first ("Shows contractor payment invoices" vs. "Get invoices"), which is mild redundancy but it also narrows scope usefully.

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 three optional params and no output schema, the description should at least hint at what comes back or how results are bounded. Annotations cover the safety profile, but an agent gets no signal on return shape, ordering, or whether the default limit of 20 applies silently.

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%, with limit, company, and statuses fully documented in the schema itself. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource (get invoices) scoped to the Deel account and to contractor payment invoices, which separates it from the generic get_invoices. It never names the closest siblings (deel_get_payment_receipts, get_invoices) for explicit contrast, so a 4 rather than a 5.

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

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

"Use when the user asks about Deel payments, contractor invoices, or payment history" gives a clear triggering context. It offers no exclusions or alternative-tool routing, such as when to prefer deel_get_payment_receipts, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is fully covered by structured data. The description adds nothing behavioral beyond that — no indication of pagination defaults, whether receipts include downloadable file links, or how results are ordered. With the annotation bar already met, this is a missed opportunity rather than a contradiction.

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, purpose first, usage second, zero filler. Nothing is redundant with the title and nothing needs trimming.

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 two-parameter list tool with rich annotations, the definition is adequate. However, there is no output schema, so the agent gets no notion of what a receipt record contains (IDs, dates, amounts, download URLs) or how results are paginated — a gap the description could have closed in one clause.

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

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

Schema description coverage is 100%, and the 'company' parameter even points at list_companies, so the schema does the real work. The description contributes no detail about 'limit' behavior (default 20) or company selection, matching the 3 baseline.

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?

Names a specific verb and resource ('Get payment receipts from Deel') and scopes it to contractor payments, so the agent knows it is not invoices or contracts. It does not explicitly distinguish itself from the near-sibling deel_get_invoices, leaving the receipts-vs-invoices boundary 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?

'Use when the user asks about specific Deel payments or needs payment proof' gives a concrete triggering condition rather than none. It offers no exclusions or alternative routing (e.g. when to prefer deel_get_invoices), so it stops short of the top score.

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 the safety profile is covered. The description adds the organizational scoping ('in the user's Deel organization'), but says nothing about the default page size of 20, pagination behavior, or how results are ordered — all relevant for a list operation.

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

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

Two short sentences with zero redundancy; the resource definition is front-loaded and the usage trigger follows immediately. Nothing is padded or repeated from the schema or annotations.

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

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

For a simple read-only, two-parameter list tool with no output schema and complete annotation coverage, the description is sufficient to call it correctly. The only gap is not clarifying its relationship to the sibling 'list_employees' tool.

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

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

Schema description coverage is 100%: 'limit' (default 20) and 'company' (which company to read, pointing to list_companies and describing the default behavior) are fully documented in the schema. The description adds no parameter meaning beyond that, 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 and resource: 'List people (contractors and employees) in the user's Deel organization', with a useful parenthetical clarifying what 'people' covers. However, it never distinguishes itself from the sibling tool 'list_employees', which an agent could easily confuse with this one.

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 when the user asks about their Deel team, workforce, or contractor list' gives clear triggering context, so the agent knows when this tool is relevant. It gives no exclusions and, notably, no routing away from 'list_employees', so the agent is left to guess between the two similar list 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, non-destructive and openWorld, so the safety profile is covered. The description adds no behavioral context beyond that – nothing about pagination, default ordering, or what a 'contract' record contains – so it earns only a baseline-with-annotations score.

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, purpose front-loaded, zero filler. No repetition of the title beyond what is needed to name the resource.

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 list tool with a fully documented schema and clear annotations, the description covers what the tool does and when to reach for it. The only gap is disambiguation from sibling people/employee/invoice tools, which matters given how many Deel-adjacent siblings exist.

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 three parameters (limit, company, statuses) are already documented in the schema, including the pointer to list_companies. The description adds no parameter meaning of its own, making the baseline 3 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?

States a specific verb+resource ('List contracts from the user's Deel account') and clarifies the domain (contractors/team members managed through Deel). It does not explicitly distinguish itself from nearby siblings such as deel_get_people, list_employees, or deel_get_invoices, so the boundary 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 second sentence gives a when-to-use trigger ('when the user asks about their Deel contracts, contractors, or team members'), which is real guidance. However, it offers no exclusions or alternatives, and its overlap with deel_get_people / list_employees means an agent cannot tell from the description which of those to pick for people-vs-contract questions.

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, and the description corroborates rather than contradicts them while adding the business consequence (cash double-counted, P&L inflated) and the return shape. The only redundancy is restating 'Read-only', which the annotations already carry, so it falls just short of the top mark.

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 purpose, then the failure mode, then the trigger phrases and the sibling routing. The parenthetical list of seven integrations is long but does establish scope. Slightly dense prose, but essentially 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?

With no output schema, the description steps in to define the return value (candidate pairs, matched/unmatched counts, date ranges, sample matched pairs, AI same-account verdict), and the single optional param is fully covered by the schema. Nothing an agent needs to call and interpret this tool is missing.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already explains the company selection and the list_companies fallback. The description adds nothing about the parameter, which is acceptable at this coverage level but not value-adding.

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?

Names a precise verb and resource (find duplicate bank accounts) and defines the exact scenario: a manual account mirroring a connected live feed, causing double-counted cash. It also distinguishes itself from the mutation path by naming merge_bank_accounts as the tool that performs the merge, so an agent can tell the two apart without inspecting schemas.

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

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

Gives explicit triggering conditions (user says cash/balance looks wrong after connecting a bank, mentions a duplicate account, or asks why P&L looks inflated) and an explicit exclusion/routing note ('Read-only — use merge_bank_accounts to actually merge a pair'). No inference required.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: results are a mix of confirmed links and AI-suggested (i.e., unverified) matches, which tells the agent to treat part of the output as probabilistic. No info on result limits or confidence scoring, but the key caveat is present.

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: what it does, what it returns, when to use it. The result-shape caveat is placed before the trigger examples, so nothing is buried and no sentence is filler.

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

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

With no output schema and full annotation and parameter coverage, the description still explains the two result categories an agent must interpret. What's missing is minor: no note on result caps, ranking, or whether suggested matches include a confidence score.

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 three parameters including the entity_type value list are documented in structured data. The description mentions amount/vendor/date/reference matching but those are internal heuristics, not inputs, so it adds nothing beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Find documents') plus the matching basis (amount, vendor, date, reference) and the result shape (already-linked vs AI-suggested). This implicitly separates it from a plain search_documents or get_document_links, but it never names those siblings to make the routing explicit.

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

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

Provides two concrete user-utterance triggers ('are there any receipts for this transaction?', 'find documents related to this invoice'), which gives an agent a clear situational hook. It stops short of saying when NOT to use it or which sibling (search_documents, get_document_links) is the alternative.

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 this to be a safe, idempotent, read-only, closed-world operation. The description adds useful behavioral context by stating that it returns the current accounting period, preparation status, and next steps. It does not mention permissions, rate limits, or failure behavior, but those are less critical for a simple read-only status tool.

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

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

The description is two sentences, front-loaded with the core action and followed immediately by return contents and usage triggers. Every sentence adds useful information with no repetition or filler.

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

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

For a simple read-only tool with one fully documented optional parameter and no output schema, the description provides enough context to call it correctly. It explains the returned information and when to use it. Minor gaps remain around sibling differentiation and explicit exclusions.

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 one optional parameter, and its schema description fully explains how to use it, including the default behavior when omitted. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate given 100% schema coverage.

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

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

The description states a specific verb and resource: getting the status of annual accounts preparation for the current company. It also lists what is returned, making the tool's purpose clear. It does not explicitly differentiate this from nearby siblings such as get_filed_accounts_history or get_deadlines.

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 usage context by naming several triggers: annual accounts, Companies House filing, year-end accounts, and corporation tax deadline. It does not explicitly state when not to use it or name alternative tools for overlapping questions.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful report semantics by explaining supplier grouping and the specific aging buckets, though it does not describe permissions, pagination, or return format beyond that structure.

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

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

The description is two tight sentences with the report definition front-loaded ahead of usage guidance. Every sentence carries useful information and there is no filler.

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

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

For a three-optional-parameter report tool with rich annotations and full schema coverage, the description is largely complete: it defines the report, its aging buckets, and when to use it. The main minor gap is that it does not explicitly distinguish this from get_bills or get_aged_debtors as alternatives.

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 company, as_of_date, and contact_id are already fully documented in the schema. The description does not add parameter-specific meaning 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 report resource and scope: outstanding bills grouped by supplier and bucketed by days past due. It distinguishes itself from related siblings such as get_aged_debtors and get_bills through the creditor/owe-focused framing and explicit aging buckets.

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 user phrases that should trigger the tool, such as "who do I owe", "what bills are due", and "show aged payables", plus the planning-supplier-payments scenario. It does not explicitly name when not to use it or point to alternatives such as get_bills or get_aged_debtors.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's 'Read-only' line is redundant but not harmful. It adds useful behavioral context by explaining the grouping and aging-bucket structure of the result, though it does not discuss limitations like date semantics or return format.

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

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

The description is compact and front-loaded: the report purpose and structure come first, followed by concise usage examples. Every sentence contributes relevant information.

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

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

There is no output schema, but the description sufficiently describes the report's grouping and aging buckets, giving an agent a clear picture of what it returns. Combined with the rich input schema and annotations, the definition is complete for this tool.

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

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

Schema description coverage is 100%, so all three parameters are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, which meets the baseline for high coverage.

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

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

The description names a specific report ('Aged debtors report'), explains exactly what it contains, and details the aging buckets. This distinguishes it clearly from siblings such as get_aged_creditors or get_invoices.

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

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

It explicitly states when to use the tool with several user-intent examples ('who owes me money', 'show aged receivables', picking clients to chase). This gives an agent clear 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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond them: the list is proactive and ranked, each item includes a plain-English reason and a location to fix it, and the agent should proactively offer help with the most important items.

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

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

The description is front-loaded with purpose and scope, then follows with usage guidance and output expectations. It is somewhat long but the enumerated categories earn their place by defining the aggregation 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?

There is no output schema, so the description carries the burden of explaining what comes back. It does so adequately by listing item categories and saying each item includes a reason and a fix location, though it does not describe the exact result shape or empty-state behavior.

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

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

Schema description coverage is 100%, and the single optional 'company' parameter is fully documented there. The description does not add parameter-level detail beyond the schema, so the baseline 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: return a proactive, ranked attention list across the whole account. It enumerates the categories included (missing statements, unreconciled transactions, deadlines, close tasks, overdue invoices, open tasks), making it clearly distinct from sibling tools that each cover only one domain.

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 strong when-to-use guidance with concrete user phrasings such as 'what do I need to do', 'what's outstanding', 'status check', and 'what should I focus on'. It stops short of naming explicit alternatives or when-not-to-use conditions, so it is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the word 'current,' which weakly implies live data but does not clarify freshness, currency, whether it's a book balance vs. bank balance, or what the return shape is. It does not contradict annotations but adds little beyond them.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity edges toward under-specification rather than optimal conciseness for a tool in a 70-sibling surface.

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

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

The tool is simple (2 optional params, rich annotations, no output schema), but the description leaves the critical ambiguity unresolved: which balance (bank, ledger, DLA, trial?) and against which company/account default. In a crowded finance toolset, that ambiguity matters more than the tool's structural simplicity.

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

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

Schema description coverage is 100%, and the company parameter's schema description is notably richer than the tool description, naming list_companies as a dependency. Per the rubric, baseline 3 applies when the schema carries the parameter documentation; the description itself adds nothing to parameter meaning.

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

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

The description states a specific verb and resource ('Get current account balance'), so the core action is unambiguous. However, it does nothing to distinguish this from siblings like get_accounts_status, get_financial_snapshot, get_bank_accounts, or get_dla_balance, all of which could plausibly return a 'balance.'

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

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

There is no guidance on when to use this versus the many balance-adjacent siblings (get_financial_snapshot, get_trial_balance, get_accounts_status, get_bank_accounts). The schema hints at a company/account selector, but the description offers neither context nor exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds essentially nothing beyond restating the as_at parameter as 'as at a given date' – no mention of what the report contains, currency/units, whether comparatives are included, or how a missing company resolves.

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

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

A single front-loaded sentence with no filler or repetition. It is efficiently sized, though the terseness is part of why other dimensions score low rather than being a conciseness flaw.

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?

Both optional parameters are fully documented in the schema and the read-only annotations cover safety, but with no output schema the description should say something about the report's contents (assets/liabilities/equity sections, period comparatives, currency) so the agent knows what it will receive.

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%: as_at is documented with format and default, and company is documented with a pointer to list_companies and fallback behavior. The description adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get Balance Sheet report') plus a scope qualifier ('as at a given date'), which is unambiguous about what the tool produces. It does not distinguish itself from close siblings such as get_trial_balance, get_profit_and_loss, or get_financial_snapshot, leaving the agent to infer the boundary.

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

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

There is no guidance on when to choose this over get_trial_balance, get_profit_and_loss, or get_financial_snapshot, nor any prerequisites or exclusions. The only implicit hint is point-in-time reporting, which the agent must read into the phrase 'as at a given date'.

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 only the scope that accounts are connected to the company; it does not mention return format, pagination, or behavior when no accounts are found.

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

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

The description is a single front-loaded sentence with no filler. For a simple list tool, this is appropriately sized.

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

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

The tool is a simple read-only list operation with full schema coverage and rich annotations. The description is close to complete, though without an output schema it could still clarify what account fields are returned or whether results are paginated.

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

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

Schema description coverage is 100%, and the single company parameter is thoroughly documented in the schema, including fallback behavior. The description itself adds no parameter meaning beyond the schema, so baseline 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 uses a specific verb and resource: 'List bank accounts connected to the company.' An agent can understand the operation immediately. It does not distinguish this tool from the similarly named sibling find_duplicate_bank_accounts, which keeps it from a 5.

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

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

It states what the tool lists but gives no explicit when-to-use guidance, prerequisites, or alternatives. The presence of find_duplicate_bank_accounts among siblings makes the absence of routing guidance a real gap.

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 the safety profile is fully covered. The description only adds the payable-vs-receivable conceptual framing, with no detail on pagination, filtering defaults, or return behavior beyond what annotations provide.

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

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

Two short sentences, front-loaded with purpose. The second sentence ('Shows what you owe to suppliers') partially restates the first, a minor redundancy, but overall efficient.

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 list tool with full schema coverage and annotations, the description is largely sufficient—purpose and direction are clear. The main gap is explicit routing versus the receivables tool, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so all four parameters (limit, status, company, contact_id) are already documented in the schema. The description adds nothing about parameters, which is acceptable given the complete schema baseline of 3.

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

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

States a specific verb and resource ('Get supplier bills/invoices') and clarifies direction with 'owed by the company... what you owe to suppliers', which separates it from a receivables tool like get_invoices. It does not name the sibling explicitly, but the payable framing is a genuine differentiator.

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

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

No when-to-use or when-not-to-use guidance, and no alternative is named. The distinction from get_invoices or get_expenses must be inferred entirely from the 'you owe' phrasing.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that. It explains what the result contains, how to interpret favorable variances, what hasBudget false means, where budgets are set, and that figures must be quoted from the result only.

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 front-loaded with the core purpose, then provides useful trigger phrases, return semantics, and the crucial hasBudget caveat. Despite being detailed, every sentence supports correct tool selection or interpretation.

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, but the description sufficiently explains the return structure and interpretation rules. Combined with the read-only annotations and fully documented input schema, an agent has what it needs to call and explain 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?

Schema coverage is 100%, so the schema already documents company, to_month, and from_month with formats and defaults. The description only indirectly connects month/quarter/year phrasing to the period parameters, so it adds little parameter-level meaning beyond the schema.

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

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

The description states the resource and purpose directly, then specifies the exact returned fields: budget, actual, variance, variance percent, totals, and net profit for income, cost of sales, and expense accounts. This clearly distinguishes it from general P&L or balance-sheet 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?

It gives explicit trigger phrases such as 'against budget', 'over budget', 'budget variance', and 'are we on track,' plus month/quarter/year comparison guidance. It also states the important exception: when hasBudget is false, say so and point to /reports/budget rather than presenting zeros.

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 safety is covered. The description adds useful behavioral context beyond annotations: GB companies receive AIA/WDA guidance from official rates, while other countries receive a jurisdiction note, and the output is framed as a hint rather than a computation.

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 are front-loaded with the core purpose, scope, jurisdiction behavior, and the key usage condition. There is no redundant or filler language.

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

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

For a low-complexity, read-only hint tool with full schema coverage and rich annotations, the description supplies enough context: what it returns conceptually, how UK vs non-UK behavior differs, and what it explicitly is not. No output schema is present, but the description adequately frames the expected 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the hint applies to a specific fixed asset, but it does not add parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: retrieving a tax capital allowance hint for a fixed asset, with the book-depreciation-vs-tax-relief distinction. It clearly bounds the tool as guidance rather than a filing computation, which separates it from computation and reporting siblings.

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

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

It gives explicit trigger conditions: when the user asks about capital allowances, AIA, or tax relief on a specific asset. It also states a clear exclusion — not a filing computation — but does not name a specific sibling alternative for that case.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the data sources behind the projection (history-derived recurring patterns, outstanding invoices, tax deadlines), which tells the agent what the numbers are built from. No mention of latency or data-freshness caveats.

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 identity (13-week cash-flow forecast) before the content enumeration and then the usage triggers. The return-value list is long but each item earns its place since there is no output schema. Slightly dense.

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

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

With no output schema, the description carries the obligation to explain return contents and does so item by item; annotations cover behavior and the lone parameter is fully documented in schema. An agent has everything needed to call and interpret it.

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

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

Single optional `company` parameter with 100% schema description coverage — the schema fully explains defaulting and how to discover companies via list_companies. The description adds nothing about the parameter, which is acceptable at this coverage level but not above baseline.

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

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

States a specific resource (13-week cash-flow forecast) and enumerates exactly what it returns: bank balance, weekly inflows/outflows/running balance, low point, recurring patterns, outstanding invoices, tax deadlines. This clearly separates it from near siblings like get_balance or get_financial_snapshot.

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

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

Gives concrete user-intent triggers: cashflow, runway, "can I afford X", "when will I run out", planning ahead. Strong positive routing signal, though it names no explicit alternative tool or exclusion (e.g. vs get_balance for a point-in-time figure).

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 fully carried by structured data. The description adds only that the categories are the ones used for categorizing transactions, with no mention of scope, pagination, or completeness of the returned list.

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

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

Two short sentences, front-loaded with purpose and followed by trigger conditions; no filler. The parenthetical '(chart of accounts)' slightly restates the title but earns its place as the common user term.

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 only two optional parameters, complete schema coverage, no output schema, and rich read-only annotations, an agent has everything needed to call it. The only real gap is the missing differentiation from list_categories.

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

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

Schema description coverage is 100% - both the type enum values and the company/default resolution rule are fully documented in the schema. The description adds nothing about either parameter, so baseline 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?

States a specific verb and resource ('List account categories (chart of accounts)') and clarifies these are categories used to group transactions. It stops short of distinguishing this from the sibling list_categories, which reads as the nearest overlap, so the agent cannot fully rule out the wrong tool from the description alone.

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

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

The second sentence gives concrete triggers - the user asking about their chart of accounts, account codes, or available categorizing categories. There are no exclusions or named alternatives, even though a sibling list_categories exists, so a common ambiguity is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is fully covered. The description adds no behavioural context beyond that — no note on default ordering, result-count limits, or what happens when multiple companies exist (that lives only in the schema).

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

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

Two short sentences with zero filler, and the resource definition is front-loaded before the usage cue. 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?

For a simple read-only list tool with fully documented parameters and rich annotations, the description covers what it does and when. The only minor gap is that multi-company scoping is left entirely to the 'company' parameter's own schema text.

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 every parameter including the subtle 'company' selector is documented in the schema and the baseline is 3. The description's mention of clients/suppliers/leads loosely mirrors the 'type' filter but adds no syntax or format detail.

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

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

States a specific verb+resource ("List contacts") and immediately disambiguates the resource with a parenthetical (clients, suppliers, leads). No sibling is named as a contrast, so it stops short of a 5, but an agent can tell this apart from get_accounts_status or list_opportunities.

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 when user asks about customers, suppliers, or contacts" gives implied trigger conditions but names no alternative tool and no exclusions. It does not clarify overlap with supplier/creditor-flavoured siblings such as get_bills or get_aged_creditors, so the guidance is useful but incomplete.

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 adds genuinely non-structured context: the meaning of the support field enumerations and the important caveat that reminder_only means AccountsOS does not produce the form.

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 purpose, no filler. The second sentence is dense with field semantics but every clause (support values, support_note, reminder_only caveat) earns its place.

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

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

With no output schema, the description usefully explains the returned fields' semantics and the reminder_only distinction, which is what an agent needs to interpret results. Only gap is the lack of a defined 'upcoming' window and no mention of defaults for include_completed.

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 both company and include_completed are fully documented in the schema. The description adds nothing about either parameter, so the baseline 3 applies; when output schema is absent it also does not state whether 'upcoming' has a default horizon.

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

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

States a specific verb and resource: 'Get upcoming tax and filing deadlines.' That is clear enough to act on, but it never distinguishes itself from related siblings such as get_vat_periods, get_tasks, or get_gov_guidance, which also surface tax/filing time information.

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 by the phrase 'upcoming tax and filing deadlines'; there is no statement of when to choose this over get_vat_periods or get_tasks, and no prerequisites or exclusions. The include_completed toggle hints at scope but the description does not elaborate.

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 closed-world scope, so the safety profile is fully covered. The description adds no further behavior — no pagination note, result volume, or ordering info. With annotations doing the heavy lifting, this is adequate but thin.

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 waste, with the purpose stated first and the usage triggers immediately after. Ideal size for a simple read tool.

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

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

Parameters, safety profile and selection triggers are all covered, which is enough to call it correctly. The one small gap is that with no output schema the description never hints at what a dividend record contains (amount, date, tax year), which would help an agent interpret results.

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%, including the non-obvious multi-company routing hint for `company`. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ("List dividend records") that no sibling competes with — none of the other get_* tools cover dividends. It's clear, but it stops short of explicitly differentiating itself from adjacent financial-list tools such as get_transactions.

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

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

Explicitly names the trigger conditions ("dividends paid, dividend history, or shareholder payments"), which is a clear when-to-use signal. It doesn't state when NOT to use it or point to any alternative, but no real alternative exists in the sibling set.

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 behavior, so the safety profile is covered. The description adds genuine domain context beyond the annotations by disclosing that results include section 455 tax warnings, telling the agent what interpretive content will come 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 short sentences with no waste; the resource and its meaning are front-loaded and the s455 warning note follows as a useful rider.

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

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

With no output schema, the description carries the return-value burden and does so reasonably by naming the balance, recent transactions and s455 warnings. It doesn't mention pagination or what the transaction entries look like, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so both the limit and company parameters are already fully documented in the schema, including the default of 10 and the cross-reference to list_companies. The description adds nothing about parameters, 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 names a specific resource (Director's Loan Account balance and recent transactions) with a clear verb, and goes further by explaining what the balance means ('director owes company or vice versa'). It is distinct enough from generic siblings like get_balance or get_trial_balance, 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 rather than stated: an agent can infer this is for checking director loan account status and s455 exposure, but there is no explicit 'use when' framing or mention of alternatives such as get_balance for general account balances. Adequate but with a clear gap.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds genuinely non-redundant behavior: a call with neither document_id nor entity_type/entity_id errors out rather than returning an empty set, and results are limited to a single entity/document per call. It stops short of describing the link record shape, which is the one remaining gap.

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

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

Front-loaded with the core constraint first, then the parameter requirement, then workflow, then example queries. Every sentence carries information; the closing quoted user-phrasings are mildly redundant with the earlier scope statement but aid trigger matching. Somewhat dense as a single paragraph.

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 could say more about what a link record contains (target id, type, maybe link kind). Everything needed to call the tool correctly — scope, parameter combination, prerequisite lookup, per-id iteration — is present.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the cross-parameter contract the schema omits: either document_id alone, or entity_type together with entity_id, otherwise an error. That is the single most important usage rule for a 0-required-parameter schema and it is stated explicitly. It doesn't clarify the company parameter's defaulting behavior beyond what the schema already says.

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 and precisely defines scope: links in either direction between exactly ONE entity and ONE document. The enumeration of entity types and the explicit 'no list-all links call' makes it distinguishable from broader document tools like search_documents or find_related_documents without opening any schema.

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

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

Gives concrete when-to-use triggers ('what documents are attached to this invoice?'), a prerequisite workflow ('look the id up first via get_transactions, get_invoices, search_documents'), and an exclusion ('there is no list all links call'). It also tells the caller to invoke once per id, which handles the multi-entity case explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is fully covered elsewhere. The description adds nothing beyond that – no pagination behavior, no ordering, no note on how large the default result set is – and 'sent to clients' mildly misleads given drafts are retrievable.

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

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

A single front-loaded sentence with no filler. It is efficient, though it is arguably too terse for a tool with filterable status values and multi-company scoping.

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 is the only place to learn what an estimate record contains or how results are shaped, and it says nothing about return fields. For a read tool whose schema is otherwise solid, this is the main 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 100% and the schema itself explains each parameter, including the cross-reference to list_companies for the multi-company case. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get estimates/quotes'), which separates it from list/invoice siblings at a glance. However, the qualifier 'sent to clients' narrows the scope in a way that conflicts with its own status filter (draft, accepted, declined, all), so the stated purpose is only partially accurate.

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

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

No when-to-use guidance and no mention of alternatives, despite obvious overlap with get_invoices, get_recurring_invoices and list_opportunities. The agent gets no signal about when estimates should be pulled instead of invoices.

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. The description merely restates the tool's purpose and adds no behavioral context such as return format, pagination behavior, or whether reimbursement requests are included in the same result set. With annotations carrying the safety burden, the description still fails to add meaningful value.

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

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

The description is a single, efficient sentence with no wasted words. However, it is under-specified for a tool with three filtering parameters and a close sibling, so its conciseness comes at the cost of actionable detail.

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

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

With no output schema and a sibling tool ('get_expenses') that is easily confused, the description should clarify the distinction and what the tool returns. It does neither, leaving the agent without enough context to reliably choose this tool over alternatives or understand the result format.

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

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

Schema description coverage is 100%, and the schema itself documents all three parameters clearly, including the 'company' parameter with a reference to 'list_companies'. The description adds no parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Get expense claims and reimbursement requests'), so the basic purpose is clear. However, it does not differentiate this tool from the close sibling 'get_expenses', nor does it explain what distinguishes expense claims from expenses. An agent must infer the distinction from the name alone.

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

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

There is no guidance on when to use this tool versus 'get_expenses' or any other sibling. No context is given about prerequisites, typical scenarios, or exclusions. The agent is left to guess based on the tool 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description contributes only trigger vocabulary and says nothing extra about ordering, pagination, or what a "claim" record contains.

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

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

Two short sentences, front-loaded with the resource, with no filler. Minor redundancy in listing "expenses" and "expense claims" as separate trigger words, but it costs almost nothing.

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 annotations, fully described three-parameter schema, no output schema, and no nested objects — the description is sufficient to call the tool correctly. The one thing an agent still cannot resolve from the description is when to prefer it over get_expense_claims.

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%: limit, status enum values, and the company/default-company rule are all documented in the schema. The description adds no parameter meaning beyond that, 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?

The description gives a specific verb and resource ("List expense claims") that an agent can act on immediately. It does not distinguish the tool from the near-identical sibling get_expense_claims, which is a real ambiguity in this toolset.

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 when the user asks about expenses, expense claims, reimbursements, or receipts" gives a clear trigger context, but offers no exclusions and names no alternatives. With get_expense_claims sitting in the sibling list, the missing when-not guidance is a material gap.

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), and the description goes further by warning that micro-entity filings yield nulls rather than zeros and that figures must not be mixed with ledger data. It does not discuss pagination or how many years are returned, a minor gap.

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

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

Four dense sentences, well front-loaded with the return contents before the usage trigger and the important caveats. Slightly long but every sentence carries distinct information (fields, when to use, comparability warning, null semantics).

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

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

No output schema exists, and the description compensates by enumerating the returned lines (balance sheet items, employees, turnover, profit after tax, reserves movement). An agent has everything needed to call and interpret results.

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

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

Schema description coverage is 100% and the single optional `company` parameter is fully documented in the schema. The description adds no parameter-level detail beyond that, 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 resource (year-by-year figures from accounts filed at Companies House) and enumerates the exact contents returned, ordered newest first. It draws a sharp line against sibling tools like get_profit_and_loss and get_balance_sheet by insisting these are registry snapshots, not ledger figures.

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

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

Gives explicit triggers (user asks how a prior year went, how the business has grown, what was filed, or wants past figures beside current books) and an explicit alternative context (live ledger tools). It also prescribes behavior: say "as filed" and never blend with live figures.

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 known. The description adds valuable behavioral context by saying this returns the exact Home dashboard headline figures in one call, but it does not discuss permissions, freshness, or performance characteristics.

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

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

The description is front-loaded with the core purpose and returned figures, then gives usage examples and sibling routing. Despite being longer than a bare-minimum sentence, every clause helps an agent choose the tool or avoid a wrong sibling.

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 snapshot tool with one optional parameter, full schema coverage, and annotations that cover safety, the description is complete. It explains what the tool returns, when to use it, and which alternatives handle adjacent questions.

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 single optional company parameter has 100% schema description coverage, including how to obtain company IDs via list_companies and default behavior when omitted. The tool description does not add any further meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('get the headline money figures') and explicitly lists the exact figures returned: cash, open invoices, open bills, and monthly net profit. It clearly distinguishes the tool from siblings like get_profit_and_loss, get_invoices, get_bills, get_aged_debtors, and get_aged_creditors.

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 use cases ('how am I doing', 'how much am I owed', 'what do I owe', quick business health check) and names alternatives for adjacent needs: past-month performance goes to get_profit_and_loss, line-level invoice/bill detail goes to get_invoices/get_bills, and ageing goes to get_aged_debtors/get_aged_creditors.

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), so the description is free to add value elsewhere. It does so by enumerating the returned fields (cost, NBV, monthly depreciation, status), which is meaningful transparency given there is no output schema. It does not mention volume, ordering, or pagination behavior, keeping it below a 5.

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

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

Three short sentences with zero waste: what it returns, when to use it, and how to filter. The core purpose is front-loaded in the first clause.

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

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

For a two-parameter read tool with full schema coverage and a clean annotation set, the description covers purpose, triggering intents, filter options, and returned fields. Only return-shape details like ordering or record limits are absent, which is a minor gap for this complexity level.

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 both the status enum and the company parameter are already fully documented in the schema, including the default of 'active'. The description restates the status values but adds no syntax or format beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Specific verb+resource ('List fixed assets on the register') plus the exact data fields returned (cost, net book value, monthly depreciation, status). An agent can clearly separate this from adjacent finance tools like get_capital_allowance_hint or get_balance_sheet without opening any schema.

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

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

Explicitly names the user intents that should route here: asset register questions, depreciation schedules, NBV, and capital items tracked per asset. It also states the status filter options. It stops short of naming an alternative tool or a when-not-to-use condition, so it is a strong 4 rather than 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?

Adds substantial context beyond the readOnly/idempotent/openWorld annotations: the 62-day threshold switches from a daily series with percentage change to monthly averages capped at 36 months, no company data is required, and 'quote rates from the result only' warns against fabrication. This is exactly the behavioral detail annotations cannot carry.

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?

Resource and mode are front-loaded, and the sentence flow (what it is → when to use → what each input shape returns) is logical. The usage examples are slightly list-heavy, but each pulls weight by mapping to a real user phrasing.

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 still fully explains return shapes (closing rate, daily series plus percentage change, monthly averages) and prerequisites (no company data). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the interaction semantics the schema only hints at – a single date returns that day's closing rate, a start/end range under 62 days returns a daily series, longer returns monthly averages. That materially clarifies how to combine date vs start_date/end_date.

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

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

Opens with a specific resource and verb ('Exchange rates: the closing rate for a currency pair on a date, or a series over a range'), instantly distinguishing it from siblings like get_income_by_currency or get_balance. An agent knows exactly what the tool returns without opening the schema.

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

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

Gives rich when-to-use triggers ('user asks for an exchange rate, FX, a currency conversion, ... whether it is cheaper to buy in one currency or another'), covering several concrete phrasings. It stops short of naming the alternative sibling or stating when not to use it, so it lands just below a full 5.

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

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

The annotations declare readOnlyHint=true, but the description says 'Maps any new accounts first,' which implies the tool may modify account mappings. That is a material side effect inconsistent with a read-only annotation, so the description contradicts the structured safety profile.

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

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

The description is compact and front-loads the core question, followed by trigger phrases and a scope caveat. The phrase 'Maps any new accounts first' is useful but conflicts with the read-only framing, making the structure slightly less clean than it could be.

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

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

For a read-only status tool with no output schema, the description covers the main checks (mapping/review status, balance checks) and clearly bounds the scope away from T2 preparation or filing. The missing piece is clarification of the mapping side effect and its interaction with readOnlyHint.

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

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

The input schema has 100% description coverage for both optional parameters, including company selection and fiscal year end. The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: checking whether the GIFI is ready for the T2, which accounts are unmapped or need review, and whether balance checks pass. It also distinguishes this from adjacent tools such as get_trial_balance and get_accounts_status by naming the T2 Schedule 100/125 context.

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 trigger phrases ('is my GIFI ready', 'GIFI mapping', 'T2 schedule 100 / 125') give clear usage context, and the final sentence clarifies that the tool prepares the GIFI trial balance rather than filing the T2. It does not explicitly say when to choose this over siblings like get_accounts_status or get_reconciliation_status, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds that it returns progress against goals and defaults to active items, but it doesn't disclose pagination, return shape, or multi-company scoping behavior. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two tight sentences with zero waste. The core purpose is front-loaded, followed immediately by usage guidance.

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, but the description states that goals and their progress are returned, which gives enough sense of the response. With fully documented optional parameters and rich read-only annotations, the definition is complete enough for an agent to invoke it correctly; only minor detail about status filtering and multi-company behavior is absent.

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

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

Schema description coverage is 100%, so all three parameters (status, company, goal_type) are fully documented in the schema. The description adds no parameter-level detail beyond the word 'active,' which is already covered by the status parameter. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Get) and resource (business/financial goals) with a scope (active) and mentions progress. It is clearly distinct from all sibling tools, none of which deal with goals. Minor imprecision: the tool can also return completed/all goals via the status parameter, so 'active' undersells its capability.

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

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

Explicitly says when to use it: when the user asks about goals, targets, or tracking against objectives. No alternatives exist among siblings, so no exclusion guidance is needed, but it doesn't clarify when to adjust the status filter to completed/all.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that the source is official GOV.UK material, which is useful, but says nothing about result format, coverage limits, or how results are ranked. With annotations carrying most of the burden, this is adequate but not rich.

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

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

Two sentences, purpose first then usage, with no filler. The example list is slightly redundant with the schema but still aids intent matching.

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 read-only, two-parameter search tool with full schema coverage and no output schema; the description gives enough to call it correctly. Only minor gaps (what results look like, whether the company parameter scopes the search) keep it from a 5.

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 and their examples are already documented in the schema. The description repeats the topic examples but adds no new semantics (e.g., query syntax, whether the company param affects scope). Baseline 3 applies.

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

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

States a specific verb and resource ('Search official GOV.UK tax and business guidance') and reinforces it with concrete topic examples (VAT, corporation tax, dividends). It doesn't explicitly name the nearest siblings (search_tax_facts, list_tax_rules) to distinguish external official guidance from internal stored rules, so it stops short of a 5.

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

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

Gives clear triggering conditions ('what does HMRC say about X?', tax rules, filing requirements) which an agent can match against user intent. It offers no explicit when-not-use or named alternative tools, so it's strong context without full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds the substantive limits — the return is prepared but not filed with CRA, a default period is assumed, and warnings may be returned. It doesn't cover partial-period or multi-company edge behavior, which keeps it short of a 5.

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

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

Front-loaded with jurisdiction and action, and the return contents and non-filing caveat each carry real information. The quoted alias list is a little long but serves retrieval matching, so it largely earns its place.

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

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

With no output schema, the description still enumerates what comes back (all lines 101–113C, balance owing/refund, due date, warnings) and states the default reporting period. Nothing an agent needs in order 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 100% and the schema already documents start/end (omit for last completed period) and company selection. The description only restates the default-period behavior, and the company parameter is not mentioned at all, so it adds little beyond the schema.

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

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

States a specific verb+resource (prepare the GST/HST return, GST34) plus the jurisdiction (Canada) and the reported outputs (lines 101–113C, balance, due date, warnings). The alias list ('what do I owe CRA', 'my Q3 GST') makes it clearly distinguishable from the VAT siblings such as get_vat_summary and calculate_vat_period.

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 routing rule: 'Always use this tool for a Canadian GST/HST figure; never add up a return yourself', plus the default-period behavior when no dates are supplied. It also draws the boundary with the filing step by noting AccountsOS prepares but does not file with CRA.

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, so the safety profile is covered by structured data. The description adds the meaningful operational constraint that it reads live from HMRC MTD and requires that integration to be connected. It says nothing about rate limits, HMRC-side errors, or what happens when no liabilities exist, so with annotations carrying the safety bar this sits at an adequate 3.

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

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

Two tight sentences: the operation and return content come first, then usage triggers and the connection prerequisite. Every clause 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?

There is no output schema, but the description compensates by stating the shape of the return (amounts owed and due dates). Parameters and prerequisites are fully covered between the description and a 100%-covered schema. The only missing piece is guidance on how liabilities differ from obligations/payments, which is a sibling-routing gap rather than a calling gap.

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

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

Schema description coverage is 100% and all three parameters (from, to, company) are documented in the schema, including defaults and the one-year capping behavior. The description adds nothing about parameter usage, 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+resource ('Read the company's VAT liabilities') and defines what a liability is (amounts HMRC says are owed, and due dates), sourced 'directly from HMRC MTD'. It does not explicitly distinguish itself from the close siblings get_hmrc_vat_obligations and get_hmrc_vat_payments, so an agent must infer the boundary.

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

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

Gives concrete trigger phrasings ('how much VAT do I owe HMRC', 'what's outstanding on my VAT account') plus a hard prerequisite ('Requires HMRC MTD connected'), which is clear usage context. It stops short of naming alternatives to use instead for obligations or payment history, so there is no explicit exclusion guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful context beyond them: the data comes live from HMRC MTD (open-world external dependency) and requires an HMRC MTD connection. Missing are any call-out on HMRC API throttling or behaviour on a disconnected account.

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

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

Front-loads the resource and its payload, then triggers, then the precondition. The long parenthetical is dense but every element is useful; only minor tightening is possible.

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

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

For a read-only tool with no output schema, the description compensates by listing the returned fields and stating the connection requirement. Pagination and behaviour for a not-connected account are the only notable gaps.

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

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

Schema description coverage is 100% and the schema already documents `from`/`to` defaults and the ~1-year range cap plus the `company` scoping rule. The description adds no parameter-level detail 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 (read) and resource (VAT obligations from HMRC MTD) and enumerates the returned fields — period keys, start/end dates, due dates, Open/Fulfilled status — which cleanly separates it from get_hmrc_vat_liabilities (amounts owed) and get_hmrc_vat_payments.

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

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

Gives three concrete user-question triggers plus a reconciliation use case, which is clear situational guidance. It stops short of explicitly naming alternatives to avoid (e.g. get_vat_periods for local periods) or exclusions, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds useful context beyond annotations: data comes directly from HMRC MTD and HMRC MTD must be connected.

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 tightly worded sentences: the first states what is read and from where, the second gives usage triggers and the connection prerequisite. No filler or repetition.

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

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

For a read-only, three-parameter tool with full schema coverage and rich annotations, the description covers purpose, source, prerequisites, and triggering questions. It does not describe return shape, but the tool is simple enough and 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 description coverage is 100%, so the schema already documents from, to, and company in detail, including date defaults and the yearly capping caveat. The description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: reading VAT payments HMRC has received, directly from HMRC MTD. This clearly distinguishes it from sibling tools like get_hmrc_vat_liabilities, get_hmrc_vat_obligations, and get_vat_periods, which concern liabilities, obligations, or periods rather than received payments.

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

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

Gives explicit user-question triggers ("has HMRC received my VAT payment", "what VAT have I paid") and a prerequisite ("Requires HMRC MTD connected"). It does not name alternatives or exclusions, but the usage context is clear.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world safety. The description adds substantive behavioral context: aggregates only (no transaction dump), defaults to money-in, bank-line scope only, invoices/ledger revenue excluded, and a subtle failure mode (no bank account returns nothing — not 'no income').

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

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

Front-loads what the tool does, then immediately provides routing examples, do-not-use guidance, defaults, and scope caveats. Every sentence carries useful information; no filler or repetition.

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

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

Although no output schema exists, the description fully describes the return shape (face totals per currency plus functional-currency total) and warns about scope limitations. An agent has everything needed to call it correctly and interpret 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?

Schema coverage is 100%, so all four parameters are already documented (company default behavior, direction default, inclusive dates). The description reinforces the money-in default but adds no syntax, format, or edge-case guidance beyond what the schema provides. Baseline 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?

States a specific verb and resource: currency-split income/expense totals broken into face totals per currency plus functional-currency total. It explicitly distinguishes itself from sibling tools (get_transactions, get_profit_and_loss) so an agent can route correctly 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?

Provides concrete user phrasings that should trigger this tool, explicitly says not to page get_transactions for summation, and names get_profit_and_loss as the alternative for book-based income. Covers when-to-use and when-to-avoid in one place.

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 elsewhere. The description adds real behavioral context beyond that: the default is waiting-messages-only (processed ones excluded unless include_processed), channels covered, and a separate count of still-processing/failed documents.

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 payload; three sentences with no filler. The final sentence is a slight restatement of the scoping idea but earns its place by disambiguating against document-search tools.

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

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

With no output schema, the description must convey the return shape, and it does: message fields, attachment/processing status, and a processing/failed count. Combined with 5 fully documented optional params, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so limit, source, company, unread_only and include_processed are already fully documented, including defaults. The description restates the processed-vs-waiting distinction but adds no format or syntax 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?

States a specific verb and resource ('Read the company's Incoming inbox') and enumerates the payload (sender, subject, preview, attachments, processing status, plus a processing/failed count). The closing sentence explicitly separates it from document-listing tools: 'Documents alone are not the whole inbox'.

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

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

Gives concrete triggers: 'whenever the user asks what is waiting in Incoming, whether anything came in, about an email or message someone sent, or before saying Incoming is clear.' No explicit when-not or named alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered, but the description still adds real context beyond them: the OAuth vs API-key provider distinction, the masked in-thread key field, and that the key is never returned (you only see connected true/false). That is useful non-obvious behavior and not a restatement of the annotations.

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

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

Front-loaded with the capability, then use cases, then the [[connect:]] mechanics. It is long and the final clauses about API keys and per-message limits are dense, but every sentence carries operational value; minor trimming is possible but nothing is filler.

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

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

There is no output schema, and the description compensates by naming the returned signals: connected/not-connected plus flowing/quiet/error, last event, 7-day event count and error message. An agent knows both when to call it and how to interpret 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?

Schema coverage is 100% and the single optional 'company' param is documented in the schema (name or id, omit for default, cross-reference to list_companies). The description adds nothing new about the parameter itself, so this sits at the baseline-with-schema ceiling rather than earning a 5.

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 ('See every integration for this company and user in one call') and enumerates the scope: connected providers, available-but-unconnected, and feed health. This clearly separates it from siblings like get_accounts_status, get_gifi_status and get_reconciliation_status, which concern ledger/account state rather than third-party connections.

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 triggers are given ('when the user asks about connections or channels', 'when something they need is not connected', 'when their data looks stale or missing'), plus the diagnostic rationale that a dead feed is often the cause of missing data. It also gives concrete operational rules: one connection offer per message, end with [[connect: provider_id]], never ask for the key in chat.

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 genuinely new behavioural context by saying the result includes summary stats on outstanding and overdue amounts, which matters because no output schema exists. It says nothing about result limits, pagination, or date-range defaults.

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: what it returns first, when to call it second. No filler, no restatement of the title or annotations.

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

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

For a read-only list tool with all-optional params, full schema coverage, and no output schema, the description covers purpose, trigger conditions, and the shape of the returned aggregates. Missing only filtering/limit behaviour and any hint about the volume of invoices returned.

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 each of the four filters (search, status, company, contact_id) is fully documented in the schema, including the cross-reference to list_companies. The description adds no parameter-level meaning beyond that, 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?

Specific verb+resource with scope: it states it returns invoices the user has *raised*, which implicitly separates sales invoices from bills, and notes the response carries outstanding/overdue summary stats. It stops short of naming the near-neighbours (get_recurring_invoices, get_bills, deel_get_invoices) that an agent must also disambiguate against in this large sibling set.

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

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

Explicitly names the triggering intents: questions about invoices, outstanding payments, or money owed to them. There are no when-not conditions or named alternatives (e.g. recurring invoice templates or aged debtors), so the agent must still infer boundaries for overlapping cases.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds only a brief domain definition and provides no additional behavioral context such as result volume, ordering, pagination behavior, or permissions.

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

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

The description is two short sentences, front-loaded with the core action and resource. There is no filler or redundancy.

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

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

Annotations cover the safety profile and the schema fully documents the optional parameters, so the description is minimally adequate. However, with no output schema, it does not describe what the returned journal entries look like or how they are ordered, leaving some context gaps.

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 four parameters are already documented in the input schema. The description adds no parameter-specific meaning or interaction details beyond what the schema provides, making the baseline 3 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: getting General Ledger journal entries. 'Double-entry accounting records' adds domain context that helps distinguish these from generic transactions, though no sibling tool is named as an explicit alternative.

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

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

There is no guidance on when to use this tool versus related siblings such as get_transactions, get_trial_balance, or get_balance. It also does not mention prerequisites, typical use cases, or exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real value: the exact semantics of the confidence percentage, an enumeration of the exception categories returned, and the default-period behaviour. It also instructs the agent to surface the returned message, which is non-obvious behavioural guidance not captured in any structured field.

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 purpose and return metric, then triggers, then defaults and follow-up behaviour — a logical order with no filler. The exception-category list is slightly long but each item is a distinct return field, so it earns its space.

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

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

With no output schema and no required parameters, the description fully carries the burden by explaining what the response contains (confidence percentage plus five exception categories) and what an agent should do with it. Nothing needed to invoke or interpret it 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?

Both parameters are fully documented in the schema (coverage 100%), including defaults and the list_companies pointer, so the description need not compensate. The description only restates the default month behaviour, adding no syntax or format detail beyond the schema, making baseline 3 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?

States a specific verb and resource ('Check how closed a month's books are') and immediately defines the returned metric as a close-confidence percentage with its exact computation. However, it does not differentiate itself from the sibling 'month_close_summary' or 'get_reconciliation_status', which an agent would plausibly confuse it with.

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

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

Gives concrete trigger phrasings ('is my month done?', 'month-end') plus a default ('last complete month'), which is strong usage context. It stops short of naming when NOT to use it or routing to alternatives like month_close_summary, so no exclusions are stated.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false and closed-world, so the safety profile is fully covered. The description adds real value by disclosing the response includes notes and activity history, but says nothing about not-found behavior or the cost/size of that history.

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 front-loaded sentence with no filler; the resource and payload are stated immediately. The only blemish is the hedged 'opportunity/deal' phrasing, which slightly blurs the domain term.

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

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

For a two-parameter read tool with rich annotations and no output schema, the description is close to sufficient, but it omits the important precondition that an opportunity_id must come from list_opportunities and says nothing about how a missing opportunity is handled.

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 both parameters are documented in the schema and the baseline applies. The description adds nothing about opportunity_id format or how the optional company parameter interacts with the lookup.

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

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

States a specific verb ('Get') plus the resource ('pipeline opportunity/deal') and even enumerates the payload ('notes and activity history'). It implicitly contrasts with list_opportunities by scoping to 'a specific' record, but never names that sibling.

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

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

Usage is only implied: 'a specific' suggests the agent must already have an ID, which implies list_opportunities to obtain one. There is no explicit when-to-use/when-not or any mention of the alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds the meaningful behavioral nuance that a configured salary with zero payroll runs means no payment went through payroll, but says nothing about empty results, multi-company ambiguity, or pagination/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?

Front-loaded with the concrete return payload before any usage guidance, which is the right ordering. The final sentence is long and carries cross-tool orchestration plus a tax-year-free interpretation rule, which is useful but slightly bloats an otherwise tight definition.

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 three returned values, and it covers the zero-payroll edge case that would otherwise confuse an agent. Minor gap remains around multi-company selection behavior, though that is largely delegated to the schema.

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

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

Schema description coverage is 100% and both parameters (company, tax_year) are documented there with defaults and a pointer to list_companies. The description adds no syntax, format, or edge-case detail for either parameter, so it sits at the baseline for a fully documented 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 (get) and resource (payroll summary) and enumerates exactly what comes back: YTD figures, last run date, next payment due. That clearly separates it from get_transactions (bank flows) and list_employees (configured salary), which the description names 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?

Gives the triggering user questions ('payroll costs', 'total salary spend', 'when the next payroll run is') and then an explicit multi-tool recipe for the ambiguous 'what have I paid myself' case, including the interpretation rule when payroll has never run. When-to-use and how-to-combine are both spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds nothing beyond that: no statement of default period, basis (accrual/cash), currency handling, or result shape, which is what an agent needs for a report tool with no output schema.

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

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

One short, front-loaded sentence with zero filler; the generic term is defined inline. It is efficient, though arguably terse to the point of under-specifying the tool's behavior.

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

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

With no output schema and zero required parameters, the description should say what the report returns and what the defaults are when from_date/to_date/company are omitted. Neither is addressed, so the agent cannot confidently call it or interpret 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?

Schema coverage is 100% and all three parameters (company, from_date, to_date) are documented with formats, so the schema carries the load. The description only restates 'for a period' without adding date semantics, defaults, or inclusive/exclusive boundary meaning.

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

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

States a specific verb and resource ('Get Profit and Loss (income statement) report') and disambiguates the accounting term with the 'income statement' gloss. It does not differentiate from close siblings such as get_balance_sheet, get_trial_balance, get_balance, or get_project_pnl, so the agent still has to guess which report to pick.

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 only usage signal is the phrase 'for a period', which hints that dates matter but never says when to choose this over get_project_pnl (project-level P&L) or get_balance_sheet, nor what happens when the period is omitted. No alternatives or exclusions are named.

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 real value beyond that by disclosing data provenance — figures are computed from bank transactions linked to the project, not from journal entries — and that commitment summaries come from invoices, bills and expense claims.

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

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

Three sentences, each earning its place: what is returned first, then when to use it, then how to supply the identifier. No filler or redundancy.

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

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

With no output schema, the description carries the burden of describing the response and does so by naming the P&L components and the commitment summaries. Combined with the read-only annotations and full schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the project_id preference and the ambiguity error on project_name. The description restates the id-vs-name routing but adds no syntax, format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a deal/project's mini P&L') and enumerates the components returned: income, costs by category, net margin, plus commitment summaries. The project scoping implicitly differentiates it from the company-wide get_profit_and_loss sibling, so an agent can route without opening the schema.

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

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

Gives concrete trigger phrasings ('how is project X doing', 'project profit', 'mini P&L for a project') and a situational cue (final report when a project completes), plus parameter routing (project_id if known, else project_name). No explicit 'when not to use' or named alternative such as get_profit_and_loss for entity-wide P&L, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds only the status grouping hint, and that hint ('pipeline, active, completed') does not line up with the schema's actual enum values (pitched, won, in_progress, completed, lost, all), which is mildly confusing rather than clarifying.

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

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

Two short sentences, front-loaded with the verb and resource, with zero filler. The only deduction is that the second clause covers statuses in a way that creates ambiguity rather than structure.

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 three fully documented optional params and complete annotations, the core call mechanics are covered. However, there is no output schema, so the description should say what a returned project looks like or whether results are paginated, and it ignores the company-scoping requirement that matters when an account has multiple companies.

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 search, status, and company are already fully documented, and the baseline applies. The description adds nothing about parameter behavior beyond loose status naming that conflicts with the schema enum, and it omits the important multi-entity 'company' scoping note.

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

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

States a specific verb and resource ('List projects') and names the status groupings it covers, so an agent knows it returns project records rather than a single project. It does not distinguish itself from near-siblings like get_project_pnl, get_tasks, or list_opportunities, which is the one thing keeping this below a 5.

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

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

'Use when the user asks about their projects, deals, or pipeline' gives a clear triggering condition and useful synonyms that broaden matchability. It stops short of naming when NOT to use it or pointing to alternatives such as get_project_pnl for financials.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description focuses on domain behavior instead: the exact returned fields, the de minimis ok/warning/breach states, per-zone smart hints, and the non-applicability guard for UK/mainland entities. That is useful context beyond the annotations, though nothing is said about what happens when the company argument is ambiguous or stale data.

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

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

Front-loaded with purpose, then return contents, then the applicability caveat, then trigger conditions — a sensible ordering. The enumeration of returned fields is dense but each item is decision-relevant; only the parenthetical smart-hint examples are borderline 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?

There is no output schema, so the description carries the burden of describing return values, and it does so concretely (qualifying/non-qualifying split, de minimis status, zone name, substance declaration, hints). Combined with the applicability condition, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single optional `company` parameter is fully documented in the schema, so the baseline of 3 applies. The description only adds the scoping notion of 'the active company's', without new syntax or selection rules beyond what the schema states.

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

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

States a specific verb and resource ('Get the active company's QFZP status for UAE Corporate Tax') and immediately enumerates what the status comprises: income split, de minimis state, zone name, substance declaration. This is clearly distinguishable from sibling status tools such as get_gifi_status or get_vat_summary.

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

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

Explicit triggering conditions are given ('Use when the user asks about QFZP status, whether they still qualify, their de minimis headroom, or whether they'll owe 9% CT'), plus an exclusion: returns applicable=false for UK or UAE mainland companies. It does not name a sibling as the alternative for those cases, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "This tool only reads" plus a routing rule to auto_match_receipts for mutation. It goes beyond annotations by documenting the per-statement row fields (period_start, period_end, opening_balance, closing_balance, book_balance_at_end, difference, agrees, document_id) and the report download link, plus an epistemic guard against over-claiming.

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 usage triggers, then return fields — a sensible order with no filler sentences. It runs long and the closing remark about the accountant report is slightly redundant with the earlier report-link mention, but every sentence still 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?

No output schema exists, so the description carries the return-shape burden and does so field by field, plus report-format options (PDF or Excel). For a zero-required-parameter read tool with only two params, nothing an agent needs to call it or interpret results is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the list_companies cross-reference for company. The description only repeats that bank_account_id narrows to one account, adding no syntax or edge-case meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (reconciliation status per bank account) and enumerates the exact content returned: each statement's opening/closing balance as printed, books' balance at end date, difference, agrees flag, unreconciled counts and newest unreconciled lines. It explicitly distinguishes itself from auto_match_receipts, which does the matching.

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

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

Gives concrete trigger questions ("does the bank agree?", "what was the closing balance in March?"), lists when to call it (before quoting any difference, reconciliation progress checks), and names the alternative tool for actual reconciliation with example phrasings. Also states an exclusion-style rule: never claim everything is reconciled without a result from this tool, get_attention or auto_match_receipts.

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 fully covered by structured data. The description adds only that these are templates rather than live invoices; it says nothing about pagination, result ordering, or whether paused records are returned by default (that lives in the schema).

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

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

Two short sentences, purpose first and trigger conditions second, with zero filler. Every clause carries information an agent would otherwise have to guess.

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

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

For a two-optional-parameter read-only list with fully described params and rich annotations, this is close to sufficient. There is no output schema, so a hint about what a returned template record contains (e.g., next issue date, amount) would have closed the last gap.

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

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

Schema coverage is 100% and both parameters are well documented there, including the 'default: active' behavior and the company-resolution hint pointing at list_companies. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('recurring invoice templates'), and the word 'templates' subtly separates it from get_invoices, which handles actual invoices. It never names that sibling explicitly, so differentiation is inferred 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?

Names three concrete user phrasings that should trigger this tool (recurring invoices, scheduled invoices, subscription billing), which gives an agent a clear selection context. It stops short of exclusions – nothing says when to prefer get_invoices or get_estimates instead.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered; the description adds the meaningful domain context that these flags gate a VAT return. It also names the exact return fields (entity_type, entity_id, label, severity, title, detail), which matters because there is no output schema. It stops short of saying whether flags are deduplicated or whether severity orders results, but that is a modest gap.

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

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

The purpose and the flag taxonomy come first, usage triggers second, return shape last — a sensible front-load. The enumeration of flag types is long but it earns its place by letting the agent match user vocabulary to this tool rather than a keyword search.

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

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

For a single-optional-parameter read tool with no output schema, the description supplies everything needed: scope, trigger conditions, the sibling it complements, and the shape of each returned flag. Nothing required to call it correctly is absent.

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

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

There is only one optional parameter and the schema describes it fully, including the fallback behaviour ('leave it out to use the only company, or the default') and a pointer to list_companies. The description adds nothing about the company parameter, which is acceptable given 100% coverage — baseline 3.

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 plus resource ('List the entries Finn flagged'), scoped to pre-VAT-return review, and it enumerates the concrete flag categories (duplicate receipts, VAT on zero-rated purchases, personal-looking purchases). An agent can distinguish this from get_attention or get_reconciliation_status 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 trigger vocabulary ('flagged, suspect, duplicate or odd entries') maps directly onto user phrasing, and it names the sibling route — entries surfaced by get_attention that need a second look. That is a real when-to-use statement with an alternative, not just an implied context.

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/closed-world safety, so the description is freed to add behavioral value — and it does, explaining that values are computed comparisons (printed statement balance vs book balance on the end date) with a derived difference and agreement flag. It stops short of noting pagination, volume, or what happens when no statements are imported.

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 and followed by the routing guidance; every clause 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?

With no output schema, the description usefully enumerates the returned fields, which is the key missing piece an agent would need. Minor gaps remain around result volume/ordering and multi-account behavior when bank_account_id is omitted.

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 both parameters are fully documented there (including the company fallback behavior). The description's 'Optional bank_account_id' merely restates the schema, adding no extra semantics such as valid id formats or behavior when the id does not match an account.

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

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

States a specific resource (imported bank statements checked against the books) and enumerates exactly what each result contains: period, printed opening/closing balance, book balance at end date, difference, and agreement flag. It is clearly not a generic reconciliation status tool, though it never names a sibling to differentiate 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?

Gives concrete trigger questions ('does the bank agree?', 'what was the closing balance in March?') and a precondition ('before quoting any reconciliation difference'). Strong positive guidance, but no explicit exclusions or named alternative such as get_reconciliation_status for an overall view.

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 nothing beyond that — no pagination behavior, default ordering, or whether completed tasks are included by default, which matters given the 'completed' filter.

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

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

A single short sentence with no filler, front-loading the resource. It is efficient but borders on under-specification rather than tight conciseness.

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 agent gets no help from the description on return shape, but the four parameters are fully self-documenting and annotations cover safety. Adequate to call the tool correctly, though thin on result semantics such as default completion filtering.

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 four parameters (limit, company, priority, completed) are fully documented in the schema, including the company fallback logic and the priority values. The description only echoes the company scoping and adds no syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (get tasks/to-dos) with clear scope ('for the company'). No sibling tool overlaps with tasks, so an agent can identify it immediately. It stops short of saying what a 'task' contains or how results are ordered, which keeps it from a 5.

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

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

The description gives no when-to-use guidance, no exclusions, and names no alternatives. An agent must infer that this is the tool for listing to-dos rather than, say, deadlines or projects.

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