Aggregate

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds much more: immediate application, 30-day undo, review-mode pending_review gating, the 7-day/±fees duplicate window, idempotency_key retry semantics, refusal when company/paid_by are missing, and the explicit 'never moves money, pays, sends or contacts anyone'. It even flags documents/memos as third-party data, not instructions.

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 tool-specific purpose before a clearly separated 'How every write tool behaves' block, so the structure is easy to scan. It is long, and a few lines (the bookkeeping-meaning examples) sit near the edge of restating general domain knowledge, but for a 17-parameter financial write tool nearly every sentence earns its place.

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

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

An output schema exists, so return values need no prose, and the description instead covers everything an agent needs before calling: required inputs, enum semantics, duplicate risk, idempotency, review gating, and the refusal condition. Nothing material is left to inference for a tool of this complexity.

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

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

With 17 parameters and only 65% schema description coverage, the description carries real load: it defines the full kind enum semantics (loan is repaid, contribution is not; transfer needs account_id and to_account_id), explains paid_by's accepted values, and clarifies idempotency_key reuse. This goes well beyond the schema's terse property descriptions.

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

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

States a specific verb and resource ('Record money that no connection shows') and enumerates the exact cases it covers: cash received, expense, reimbursement, owner loan/contribution, intercompany, transfer. An agent can distinguish it from add_invoice or record_payment purely from this first sentence, and the 'kind decides the bookkeeping' clause maps each enum value to meaning.

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 scopes when to use it ('money that no connection shows') and when not to (a Stripe payout is not revenue, a card payment is not an expense, cash later deposited is a transfer, not income). It also routes the agent to siblings: search_transactions/search_invoices to find likely duplicates and update_record to link, with duplicates surfacing in possible_duplicates.

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

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

Goes well past the annotations (which only say non-read-only, non-destructive, idempotent): immediate apply with 30-day undo, review-mode 'pending_review' wait, refusal when company/whose-money are missing, duplicate detection inside possible_duplicates, idempotency-key retry semantics, prompt-injection warning, and the explicit 'never moves money' guarantee.

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 a clearly headed bullet block. The 'How every write tool behaves' section is largely generic boilerplate that costs length, but each bullet carries decision-relevant content (review mode, duplicates, bookkeeping meaning) rather than filler.

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

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

For a 17-parameter, 8-required mutation tool with an output schema, this covers what the agent needs: what gets recorded, what can be refused, approval behavior, duplicate handling, and that output describes the record and suggested links. Return-value detail is correctly left to the output schema.

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

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

Schema coverage is only 35% across 17 params, so the description must compensate and largely does: it decodes the side enum, states that lines plus tax must equal total (and that mismatches are flagged not rejected), and pins down idempotency_key and company semantics. Uncovered params (note, due_date, status, file_sha256, source_document_id) get no mention, leaving some gap.

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

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

Specific verb+resource+scope: 'Record an invoice you sent (owed_to_you) or a bill you received (you_owe) that no connection shows'. The side enum values are decoded inline, so the agent can tell this apart from connection-synced records and from query/search tools 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 a clear trigger ('a paper or emailed bill' that no connection shows) and names alternatives for the adjacent problem — search_transactions/search_invoices to find already-synced money and update_record to link it. It does not explicitly route between this and other write siblings such as add_entry or record_payment, so guidance is strong but not 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?

Goes well beyond the annotations: it explains that later changes post as adjustments on the next open day, that the result is status 'pending_review' with an approval_url, that an owner/admin finalizes in Aggregate, and that undo restores the previously enforced lock. These are exactly the consequences an agent needs for a destructive:true tool, and nothing contradicts the hints.

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 tool-specific opening is front-loaded and efficient, but roughly half the text is a generic 'How every write tool behaves' block covering duplicate detection, bookkeeping semantics, and transfers that is not specific to closing a period. That bulk dilutes 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 an output schema present, the description need not detail return values, and it still covers approval flow, permissions, undo, and post-close adjustment behavior. The remaining shortfall is that some of the space is spent on shared boilerplate rather than close-specific edge cases (e.g., what happens if the date is already closed).

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds real semantic context: 'through' defines the lock boundary such that later-dated changes roll forward, and idempotency_key semantics (retry returns the original record) are reinforced. It does not, however, add anything about dry_run that the schema lacks.

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 ('Closes a company's books through a past date') and immediately explains the effect of the action. It is clearly distinguishable from the sibling reopen_period, which performs the inverse.

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 a concrete trigger ('after a month or year is reviewed') and permission context ('Available to connections made by owners and admins'). It notes the undo path but does not explicitly name reopen_period as the alternative for reversing a close.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description goes further by disclosing immediate application with a 30-day undo, the pending_review approval path, idempotency_key retry semantics, and that company is never inferred and a write without it is refused. However, several bullets (recording amount/currency/counterparty, duplicate bank-sync matching, bookkeeping treatment of Stripe payouts and card payments) are generic write-tool boilerplate that does not apply to creating a bucket, diluting relevance.

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 first sentence is well front-loaded, but it is followed by ten boilerplate bullets labeled 'How every write tool behaves', most of which (duplicate detection, bookkeeping meaning of payouts and transfers, idempotency across all writes) are irrelevant to creating a bucket. The volume of generic text buries the few behavior notes that actually matter here.

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

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

For a write tool with nested objects and an output schema (so return values need not be described), the definition covers mutation semantics, schedule and rule shape, and the refusal condition. It falls short on the unresolved parameters (values, reason, fields) and never clarifies how the bucket then relates to get_bucket/list_buckets, leaving useful gaps at 44% schema coverage.

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

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

Schema description coverage is only 44%, so the description has to compensate, and it partially does: it names the schedule fields (amount, cadence, due day, end) and explains that the field's rule routes matching transactions. But it says nothing about the 'fields', 'values', or 'reason' parameters, and 'values' has no schema description either, leaving real parameters undocumented in both places.

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

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

The opening sentence gives a specific verb and resource (create a bucket) and enumerates the optional components it can carry – custom fields, schedule, routing rule – with concrete examples (Rent, Loans, Contractors). It is clear what the tool does, but it never distinguishes itself from adjacent siblings such as create_rule or update_bucket, even though the 'rule' concept overlaps with create_rule.

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

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

Usage is only implied: the rule parameter description of routing matching transactions hints at when a bucket is appropriate, and the duplicate bullet points to search_transactions/update_record for a different task. There is no explicit statement of when to choose create_bucket over create_rule, add_entry or update_bucket, and no prerequisites beyond the refusal note.

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

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

Goes well beyond the annotations (idempotentHint, destructiveHint=false) by disclosing the immediate-apply/labeled/30-day-undo lifecycle, the pending_review wait when review mode is on, duplicate detection rules (same amount ± fees, within 7 days, same counterparty, surfaced in possible_duplicates), the required company/whose-money precondition, idempotency_key retry semantics, and a prompt-injection warning that document text is data not instructions. It also scopes blast radius ('changes Aggregate records only... never moves money').

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 tool-specific purpose before a bulleted block of shared write-tool behavior, which is scannable and largely earns its place (undo window, review mode, duplicates, required fields). The generic block is longer than this tool strictly needs, but nothing is redundant or restated for its own sake.

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

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

For a nested-object, 8-parameter mutation with an output schema available, the description covers everything an agent needs to call it safely: mutation semantics, approval flow, required non-inferred fields, idempotency, duplicate handling and safety boundaries. Return-value detail is correctly omitted since an 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?

At 75% schema coverage the baseline is 3, but the description adds real meaning: the match object is characterized as a search_transactions query plus description text, counterparty, amount range and account, and the set object as category/bucket/kind/company/counterparty rename. dry_run, reason, stop_processing and apply_to_existing are left to the schema.

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

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

States a specific verb+resource (create a rule) plus its full scope: deterministic matching on query/description/counterparty/amount/account, applying a category/bucket/kind/company/counterparty name now and in future syncs. Distinguishes it from siblings like search_transactions (which only previews) and update_record (which links existing rows).

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: it explains that a search_transactions query becomes the rule as-is, so the search previews what the rule will catch, and mentions update_record for de-duplication. However, there is no explicit 'use this when / not when' framing or a named alternative for one-off categorization, so the agent must infer the intended workflow.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds meaningful behavior beyond them: visibility is scoped by role (owners/admins see everything, others only their own and their AI connections'), results are limited to companies the connection covers, and argument amounts are redacted. These are non-obvious data-shaping traits an agent needs before trusting the output.

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 dense sentences, front-loaded with the resource and ordering, then scoping, then redaction. The parenthetical enumerations carry real information, though the sentence structure is heavy enough that it is informative rather than maximally crisp.

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 does the work of explaining returned fields (actor, time, record, company, status) and access scoping, which is strong. It stops short of describing the pagination cursor (next_before_seq) surfaced by before_seq, leaving that 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 67% (before_seq and only_this_connection are documented inline; limit is not). The description adds only the 'newest first' ordering cue and says nothing about limit, cursor semantics, or the connection-only filter, so it does not compensate for the gap. 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?

Names the resource precisely (the activity log) and enumerates its contents: actor type (people, AI connections, syncs, email-in), timestamp, target record and company, and disposition (applied, held, denied, failed). The ordering ('newest first') further distinguishes it from sibling read tools like get_record or list_review_items.

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

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

The description conveys what the tool is for, and the scoping language implies it is the per-connection activity view, but it never states when to reach for this versus get_record, list_review_items, or query_transactions, nor any exclusion. Usage is inferable rather than 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description does not contradict it. The description adds one genuinely useful behavioral fact: the result includes all payments regardless of status (paid, upcoming, missed). It stops short of describing error behavior for a missing bucket or any size/limit 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?

A single front-loaded sentence with no filler, and the parenthetical enumeration of payment statuses efficiently conveys scope. It is slightly clipped – a verb like 'retrieve' would have cost nothing – but nothing is wasteful.

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 does useful work by describing the shape of the return payload, and annotations cover the safety profile. However, for a 40+ sibling tool set it omits the routing context an agent needs (when to prefer this over list_buckets or get_overview) and says nothing about failure modes for an unknown id.

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

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

Schema description coverage is 0%, so the description technically carries the burden, but the single required 'id' parameter is self-documenting via its schema type and constraints. The phrase 'a bucket' implicitly conveys that the id selects exactly one bucket, yet the description adds no format, length, or lookup details beyond that.

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

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

The description names the specific resource ('a bucket') and enumerates its payload (fields, schedule, rules, every payment), and the singular framing makes it distinguishable from list_buckets, create_bucket, and update_bucket. It lacks an explicit verb such as 'retrieve', so the action must be inferred from the name/title, but the resource scope is unambiguous.

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

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

There is no statement of when to call this versus list_buckets, get_overview, or get_activity. Usage is only implied by the singular resource, and no preconditions (e.g. the bucket must exist, an id is required) are mentioned.

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 safety is covered. The description earns credit by disclosing output semantics the annotations cannot: amounts are in their own currency, *_home fields are converted to the company currency, and those fields are null when no FX rate exists. It stops short of stating pagination or result-size behavior.

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

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

Two sentences with no filler. The scope and content list come first, then the currency caveat that an agent would otherwise get wrong. 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 must carry the return shape, and it does — listing the sections and the currency-conversion rule. It is complete enough to call correctly and interpret the response, though it says nothing about size limits or whether results can be filtered or 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 coverage is 100% — the single 'company' parameter already documents name-or-id, 'Personal', 'all', and the omit-for-all behavior. The description adds only the phrase 'per company', which is consistent with the schema but adds no new syntax or constraint.

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 (fully diluted cap table) and enumerates the exact contents returned: holders, share classes, SAFEs/notes, option pool, RSUs, warrants, last 409A. No sibling tool overlaps this domain, so differentiation is implicit rather than stated, which holds it just below 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?

There is no when-to-use, no prerequisites, and no alternative named. The closest it comes is mentioning 'per company', but that reads as scope, not guidance; the agent must infer this is the tool for equity ownership 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description usefully adds that it aggregates current-year and all-time totals, open items, and payment timing, but says nothing about auth scope, result size, or behavior for an unknown name_or_id.

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

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

A single front-loaded sentence that leads with the scope ('Everything about one customer or vendor') then lists the data included. Dense but every clause carries retrieval-relevant content, with 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?

With no output schema, the description does the heavy lifting on returns and covers them well (totals, open invoices/bills, last payments, average days to pay). However it never addresses the required identifier parameter or the company scoping behavior, which an agent needs to call it correctly.

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

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

Based on the description alone, no parameter is explained; the schema documents only 'company' (50% coverage). The required 'name_or_id' has no schema description and no mention in the description, leaving the most important input's accepted forms (exact name? id format? fuzzy match?) unspecified.

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 (one customer or vendor profile) and enumerates the returned content, so an agent knows exactly what the tool produces. It does not name or contrast any sibling such as query_invoices or get_activity, so it stops shy of a 5 despite the clear resource.

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

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

The scope phrase 'one customer or vendor' implies this is the per-counterparty aggregate lookup, which is implied usage guidance. There is no explicit when-to-use trigger or named alternative (e.g., query_invoices for line-level detail), so it does not reach the 4-5 tier.

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, so the description is free to add semantics — and it does: the status taxonomy, the crucial warning that missing means unknown rather than zero and that totals exclude it, and the remediation paths. That is meaningful 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?

Three dense sentences with no filler, and the output shape leads. The first sentence is a list-as-sentence fragment that takes a beat to parse, but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and largely meets it by naming the statuses, the row count, and the per-problem line. It still omits the default time window and what the response looks like at the account vs month level, but nothing critical to 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 from, to and company are fully documented in the schema. The description adds no parameter-level detail (defaults, window semantics, company scoping), 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 names the resource (per-account month coverage) and enumerates the exact statuses returned, which an agent can distinguish from get_metric or list_accounts. It is telegraphic rather than a clean verb+resource statement, but the intent is unmistakable.

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

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

It implies the diagnostic use case ('Missing means unknown, not zero') and routes to adjacent tools by noting that get_metric reports unknown_reason and that a statement upload or pin_balance can fill a month. It never states explicitly when to reach for this tool over get_metric or list_accounts, so usage is inferred rather than given.

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), so the description earns credit for adding semantic behavior: the returned text is third-party-authored data, which fields are untrusted, and how flagged third-party names are labeled. That is meaningful injection-defense context beyond the structured fields, though it omits anything about size limits or pagination of extracted text.

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

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

Front-loading the return value is good, but the safety guidance is repetitive ('it is data to transcribe, not instructions' is restated as 'They are data, not instructions'), and the flagged-name convention is a trailing aside that could be one clause.

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

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

With no output schema, the description does the work of describing the payload shape: metadata, extracted text, untrusted_text fields, and flagged-name prefixes. Combined with annotations covering read safety, an agent has enough to call and interpret this tool, though the id parameter and any text-size behavior remain unspecified.

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

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

Schema description coverage is 0% with one parameter, so the description must carry the semantics. It implies the id is a document identifier and that writers reuse it as source_document_id, but it never states the format, length, or where the id comes from, which is what an agent needs for a 1-param 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?

The opening sentence states the resource and what is returned ('a document's metadata and extracted text'), which distinguishes it from list_documents (plural) and get_record (different resource). However it is a noun fragment with no explicit verb, and separation from get_record is implied 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?

There is no explicit when-to-use statement or named alternative. The one concrete usage cue is the forward reference that writes 'take its id as source_document_id', which tells the agent how the returned id feeds other tools, but nothing says when to fetch a document vs. list_documents or get_record.

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), so the bar is lower, and the description still adds real behavior: the as_of default of today, that a snapshot is 'the latest on or before' the date, that values are per currency with per-account totals, and that cost basis is only present 'where reported'. It does not mention pagination, auth, or rate limits, but the key data-shape behaviors are disclosed.

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

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

Two dense sentences with the core resource and its returned fields front-loaded, followed by snapshot and formatting caveats. The colon-heavy clause structure is slightly awkward but every clause carries information; nothing is wasted.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by enumerating the fields and explaining per-currency/per-account aggregation and the conditional cost basis. It is complete enough for an agent to call and interpret the result, with only minor gaps like no mention of account_id sourcing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it by clarifying the as_of default ('default today'), the snapshot semantics, and the decimal-string quantity format for fractional shares. These details help interpret the returned data even though the parameters themselves are already documented in the schema.

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

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

The description names the resource (positions in investment accounts), enumerates the exact fields returned (security/ticker/name, quantity, price, value, cost basis), and explicitly draws the boundary against the sibling list_accounts ('Account balances themselves are in list_accounts'). An agent can distinguish it from get_bucket, get_cap_table, and get_liabilities 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?

Usage is implied rather than stated: it routes account-balance questions to list_accounts and explains the as_of snapshot semantics, which helps an agent decide what the tool is for. But there is no explicit when-to-use framing, no prerequisite (e.g. needing an account_id from list_accounts), and no other alternatives named despite many sibling get_* 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?

Adds meaningful context beyond the read-only annotations: it discloses that the data is 'as the bank last reported them (as_of)' and that unreported fields are 'left out, not zero.' The latter is an important quirk that helps the agent interpret results. It does not discuss rate limits or auth, but for a read-only lookup this is solid.

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 dense sentence that front-loads the return payload, followed by two short routing/clarification clauses. Every clause earns its place, though the field enumeration is long.

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, no-output-schema fetch with one optional parameter, the description tells the agent what fields come back, where related data lives, and how missing values are represented. It is complete enough to call correctly, missing only return-shape/pagination nuance.

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

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

Schema coverage is 100% and the single parameter ('company', with Personal/all semantics) is fully documented there. The description adds no new parameter details, so the baseline 3 applies – the schema carries the parameter burden.

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 (returns credit card and loan terms) and enumerates the exact fields returned. It also delineates scope by telling the agent where current balances (list_accounts) and upcoming minimum payments (list_upcoming) live, distinguishing it from those 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?

Explicitly routes the agent to list_accounts for current balances and list_upcoming for upcoming minimum payments, which is clear 'for X use Y' guidance. It does not state exclusions or when not to call it, but the field-level scope makes its purpose unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that: it discloses that values are never estimated, that they match the in-app view, and that results may include stale sources, pending-review items and AI-added entries — data-quality traits an agent could not infer from annotations.

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

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

Two sentences, front-loaded with the core definition and then the caveat about row sums. Dense but every clause carries substance; the enumerated result fields are somewhat list-like but not redundant.

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

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

With no output schema, the description correctly enumerates the returned fields an agent needs to know about. It is close to complete for a single read-only retrieval tool; the main omission is the default time window when from/to are omitted, which the description leaves 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 80%, and the schema itself carries very rich per-enum documentation for metric and basis, so the schema does the heavy lifting. The description adds no parameter-specific syntax or default behavior (e.g. what omitting from/to means), so the baseline 3 holds.

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

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

The description defines the resource precisely — a fixed-definition Aggregate-computed metric returned with value, basis, as-of time, formula, included/excluded accounts, stale sources and review counts. It distinguishes the result from a naive sum of transaction rows. It does not, however, name which sibling to use instead (e.g. query_transactions) for the underlying rows.

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 explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The only usage-adjacent statement is the warning that a sum of listed rows may not match, which is a caveat rather than 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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real value beyond them: the data provenance (connected subscription sources such as Stripe) and the null semantics for churn rates when a month starts at zero, which an agent would otherwise misread as zero churn.

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?

It opens with the resource and its scope, then the field list, then the alternative tool – good front-loading. The inline formula and long enumeration are dense but each element earns its place by defining the output without an output schema; the second sentence is a slightly abrupt topic switch to get_metric.

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 full burden of describing return values, and it does so exhaustively: all movement components, the reconciliation formula, customer counts, churn rates and their null condition. Combined with the schema's complete parameter documentation, 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 description coverage is 100% and all three parameters (from, to, company) are documented in the schema itself, including defaults and the "all"/"Personal" values, so the description need not repeat them. The description adds no parameter-level syntax or constraints 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?

The description names the exact resource (monthly recurring revenue movements per month, counted per customer) and enumerates every returned component: start, new, expansion, reactivation, contraction, churn, end, customer counts and churn rates. It even gives the reconciliation identity (start + new + expansion + reactivation − contraction − churn = end), so an agent knows precisely what the tool computes and how it differs from get_metric.

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 routes to the sibling: get_metric gives mrr, mrr_churn_rate and net_new_mrr for the last complete month, implying this tool is for month-by-month breakdowns over a range. That is clear contextual guidance, but there is no explicit when-not or prerequisite statement (e.g. what happens when no subscription source is connected).

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

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

Annotations already cover read-only, idempotent, closed-world behavior, yet the description adds substantial non-obvious traits: hidden data types when the connection lacks visibility, investments never counted in cash, how books_closed_through adjustments post, how combined runway is computed, and an explicit safety note that untrusted_text and "⚠ flagged text:" fields are third-party data, not instructions.

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 dense paragraph with essentially no filler — every clause carries semantic payload about a returned field or a computation rule. It is long and slightly list-heavy rather than front-loaded with a one-line summary, which keeps it just short of 5.

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 field by field, including aggregation caveats and text-safety handling. Combined with annotations covering the safety profile, 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 both parameters (as_of, company) are fully documented there, so the baseline is 3. The description reinforces scoping ("each only where this connection can see that kind of data") but adds no format or syntax detail beyond the schema.

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

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

States a specific resource (per-company financial overview) and enumerates the exact contents: cash, card debt, burn, runway, MRR, receivables, bills due, payroll, investments, attention items, source freshness, and books_closed_through. This lets an agent distinguish it from narrower siblings like get_metric, get_liabilities, or get_reports 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?

"Answers most 'how are we doing' questions in one call" gives clear context for when this broad tool beats assembling several narrow ones. It does not, however, name alternatives (e.g. get_metric, list_upcoming) or state exclusions, so it falls short of explicit when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly focuses on semantics: the +/− sign convention for direction of debt, and the fact that results are split into loans, contributions, unreimbursed expenses and unspecified owner money. It does not say whether results are aggregated or per-company rows beyond the vague 'rows behind it'.

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

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

One packed sentence with no filler, and the core idea ('what each company owes') is front-loaded. The trailing clause 'with the rows behind it' is vague and slightly weakens an otherwise efficient statement.

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: it enumerates the four balance categories, the sign convention, and hints at underlying rows. It omits currency, aggregation level, and record counts, which leaves minor gaps for a no-output-schema financial read 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% and the single optional 'company' parameter already documents the accepted values ('company name or id, Personal, all', omit for everything visible). The description adds nothing about the parameter, 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 names the resource (owner balance per company) and the scope (the person behind this connection), plus the sign convention and the four breakdown categories. An agent can distinguish it from list-style siblings, though it never explicitly positions itself against lookalikes like get_liabilities or get_holdings.

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 when-to-use statement, no prerequisites, and no named alternative. The closest thing to guidance is the phrase 'what each company owes the person behind this connection', which only implies the use case. An agent must infer when this beats get_liabilities or get_overview.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds value beyond them by disclosing the admin-rights requirement for the "people" detail level. It does not mention pagination or default date-range behavior, which is the remaining gap.

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

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

Two tight sentences with no filler, and the return-content list is front-loaded before the detail-level caveat. The telegraphic style is dense but readable and 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 usefully enumerates what the call returns and the one access constraint, which is enough for an agent to call it confidently. Minor omission: no statement of default date window or what an omitted date range returns.

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 low at 25% (only "company" is documented in the schema), so the description carries extra burden; it clarifies the "people" enum value meaning and its permission requirement, which the schema does not. However, it says nothing about from/to semantics or defaults, leaving half the parameters dependent on bare patterns.

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 and enumerates the returned metrics (gross, employer taxes, net, total cost, next run estimate, headcount, contractors), which lets an agent distinguish it from sibling aggregates like get_metric or get_reports. It stops short of naming a sibling it is not, but the payroll-specific scope is unambiguous.

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

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

Gives an explicit conditional: per-person pay is only returned with detail "people", and that mode requires payroll admin rights, which is a real prerequisite an agent must check. It does not contrast with an alternative tool, but the mode selection guidance is concrete and actionable.

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 annotations (which already declare readOnly/idempotent/non-destructive): it discloses an audit trail including which AI made changes, voided state, the response_format tradeoff, and a security-relevant note that untrusted_text holds third-party data not instructions. That is genuinely useful behavior for a read tool. It stops short of stating return shape, pagination, or error behavior when an id is missing, so it is 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?

Dense but front-loaded: the resource and verb lead, followed by what the record contains, then the important untrusted_text caveat. Every sentence carries weight, though the long parenthetical type list and the final flagged-text sentence make it slightly heavy.

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 no output schema, the description covers the record contents, links, audit/voided state, the concise/detailed tradeoff, and a prompt-injection warning — more than the annotations provide. It could still state behavior on invalid ids, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 50%: id has no schema description, but the description implies it is the Aggregate id covering many record types, which adds meaning. response_format is already fully documented in the schema, so the description adds nothing for it. Baseline 3 fits since the schema handles the enum and the description only partially compensates for the id parameter.

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

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

States a specific verb (get) and resource (any record by id) and enumerates the resource types covered (transaction, invoice, bill, entry, payroll run, etc.), clearly distinguishing it from the many list_/query_/search_ siblings that filter collections rather than fetch by id. The scope is unambiguous.

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

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

Implicitly frames usage as fetching a full record given an Aggregate id, but never states when to prefer this over get_document, get_bucket, or get_activity, nor the precondition that a valid id is required. No explicit when-not guidance, so usage is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that figures come 'from the ledger' for a bounded period and that basis affects the result, which is genuine context, but it says nothing about whether unclosed periods are included or how the statement is delivered.

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 tight sentence with no padding, and the report kinds are front-loaded. It reads as a noun phrase rather than a verb-led statement, so the action is inferred from the tool name rather than stated.

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 flat, read-only report tool with no output schema and annotations covering safety, the description delineates the full input space (kind, period, company, basis) at a conceptual level. Only the edge cases around company scoping and the return shape are left implicit.

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

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

Schema description coverage is only 20% (only 'company' is documented), so the description has to carry weight — and it does cover the concepts behind kind, from/to (period), basis and company. It still omits the date format, the accrual default, and the accepted 'Personal'/'all'/omit-for-all company values, so it compensates only partially.

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

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

The description names the exact artifact produced (profit and loss, balance sheet, or cash flow statement) and its scope (per company, from the ledger, for a period, cash or accrual basis). That maps cleanly onto the enum and other params, so an agent knows precisely what it gets. It does not, however, differentiate itself from nearby read tools like get_metric or get_overview.

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 statement of when to reach for this tool versus alternatives such as get_metric, get_overview, or query_transactions, and no prerequisites (e.g., period must be closed, or which company values are valid) are given. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds real value beyond that: account numbers are truncated to the last 4 digits and a last-sync timestamp is included. It stops short of noting pagination, ordering, or whether closed accounts appear by default.

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 scope and followed by the one non-obvious privacy detail. Nothing is wasted and no filler is present.

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, enumerating returned fields is genuinely useful and largely complete for the data shape. However, for a 3-parameter tool it omits the meaning of include_closed and the type enum values, and says nothing about result size or ordering.

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

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

Schema description coverage is only 33%: 'company' is documented in the schema, but 'type' (an 11-value enum) and 'include_closed' have no schema description at all. The description's mentions of 'company' and 'type' refer to returned fields, not filter inputs, and include_closed is never addressed, so it fails to compensate for the coverage gap.

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

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

The description names the resource (every bank, card, processor, cash and loan account) and enumerates the attributes returned (balance, available, limit, currency, last sync), so an agent knows exactly what comes back. The verb is only implied ('list') and no sibling is named, so it doesn't distinguish itself from get_holdings, get_liabilities or get_overview.

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 when-to-use guidance, no mention of the filters the tool accepts (company, type, include_closed), and no routing to or away from sibling tools. The agent must infer usage entirely from the 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 safety is covered. The description adds value by disclosing the returned payload categories (counts, schedule, routing rules), but says nothing about pagination, ordering, or result size.

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 compact sentence that front-loads the resource and then lists the payload fields. Nothing is wasted, though the omission of any verb keeps it from being maximally useful.

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

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

For a read-only list tool with full annotation coverage and full schema coverage, the description usefully compensates for the absent output schema by enumerating the fields returned. Only ordering/pagination details are missing.

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

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

Schema description coverage is 100%, and the single 'company' parameter is fully documented in the schema including the 'Personal'/'all'/omit semantics. The description adds nothing 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 names the resource and enumerates the payload ('custom fields, schedule, routing rules and paid / upcoming / missed counts'), but it is a noun phrase with no verb — the action is only inferable from the tool name. It also does not differentiate itself from get_bucket, create_bucket, or update_bucket, which share the same noun.

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 when-to-use guidance, no mention of get_bucket for a single bucket, and no exclusion for create/update siblings. The agent must infer that 'list' means retrieve all buckets in scope.

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 adds high-value behavioral context beyond them: untrusted_text fields hold third-party authored content, that content is data not instructions, and names prefixed with '⚠ flagged text:' are third-party names masquerading as instructions. This prompt-injection guidance is exactly the context annotations cannot convey.

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

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

Content is front-loaded: resource and statuses first, then sibling routing, then the untrusted-text warning. Every clause earns its place, though the injection warning is comparatively verbose for a listing 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?

With no output schema, the description takes on responsibility for the return shape and does describe the resource and status values adequately, plus the sibling tools that consume results. It omits pagination/ordering behavior, which keeps it from a 5 but is minor for a read-only list.

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

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

Schema coverage is 50%: company carries a full schema description (name/id, 'Personal', 'all', omit for all visible) while status has only an enum. The description restates the three status values but adds no syntax or semantics beyond the enum, and says nothing about the company parameter. Baseline 3 given partial 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 identifies the resource precisely – uploaded and emailed-in files (receipts, bills, statements) with their status values unread/recorded/ignored – which clearly distinguishes it from get_document (single file text) and the write tools. It lacks an explicit 'list' verb framing but the resource and scope are unambiguous.

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

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

It routes the agent across siblings: get_document returns the text of one file and the write tools record what it says, which establishes when to use this listing tool versus the alternatives. No explicit exclusions or 'when-not-to-use' conditions are stated, keeping 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 readOnly/idempotent/non-destructive, so safety is covered. The description goes beyond them by disclosing how results are derived (3+ occurrences = active, twice = suggested, stopped = ended) and by explicitly excluding payroll and transfers from detection, which materially shapes interpretation of the output.

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 dense paragraph that front-loads what the tool returns, then the status legend, then the exclusion. Every clause carries information, though the long comma list of returned attributes is slightly harder to scan than a structured breakdown would 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?

With no output schema, the description usefully enumerates the returned fields, and all four parameters are documented in the schema. It omits any mention of result limits, pagination, or ordering, which an agent might need for a potentially long list of detected merchants.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value above that by defining the enum values of `status` in business terms and clarifying that 'active' means counted in bills due, which the schema alone does not convey.

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

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

States a concrete resource (subscriptions and recurring bills detected from bank/card charges) and enumerates the specific attributes returned (price, frequency, next expected charge, late flag, price changes, converted trials). An agent can distinguish this from siblings like list_upcoming or get_payroll without reading the schema.

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

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

The description explains the meaning of each status value (active = seen 3+ times and counted in bills due, suggested = seen twice, ended = stopped), which implicitly guides filter choice, and rules out payroll/transfers as content. However, it never states when to pick this tool over the adjacent sibling list_upcoming, leaving tool selection partly 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, idempotentHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds a useful conditional visibility rule (which_company shown only when the person manages the workspace) and an exclusion note, but no pagination or ordering behavior. Adds some value over annotations.

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

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

Front-loaded with the core purpose and a compact enumerated list, then the routing and exclusion notes. The who/which-company parenthetical is dense but earns its place by explaining a conditional visibility rule.

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 no output schema, the description covers what is returned, excludes the held-for-review case, and notes a conditional visibility rule. It leaves the kinds filter semantics implicit, but overall complete enough for correct invocation.

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

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

Schema coverage is 50%: the company parameter is fully documented in the schema, but the kinds array lacks any prose explanation in the description. The description enumerates the kinds in natural language (suggested matches, possible duplicates, suggested rules, whose-money, which-company, unread documents), partially compensating for the missing kinds param docs, aligning with a 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?

States a specific resource (items waiting for a decision) and enumerates the exact kinds it returns, distinguishing it from sibling resolve_review_item which settles them. An agent can tell this is the worklist tool 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?

Explicitly routes to resolve_review_item (settles them), and clarifies the boundary that AI changes held for review are handled elsewhere in Aggregate. Strong context, though it doesn't state when to filter by kinds vs. fetch 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: each item carries a confidence label (scheduled, recurring_detected, estimated) and, importantly, that 'each kind shows only where this connection can see its data' — a visibility/permission constraint the agent cannot infer from annotations or 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 dense sentences, with the core purpose front-loaded before the kind enumeration. The long middle list of kinds is justified by the lack of enum descriptions in the schema, though it reads as a run-on and slightly dilutes the opening.

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 correctly describes returned fields (date, amount, confidence) and the visibilty caveat, which is what an agent needs to interpret results. It omits the days default/cap and any note on ordering or volume, leaving minor gaps for a forecast 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 only 33% (only 'company' is documented in-schema), so the description has to carry weight. It clarifies 'next N days', maps the kinds values to human terms (card and loan minimum payments for payment_of card or loan), and explains the confidence vocabulary. It does not mention the default of 30 days or the 180-day cap, so it is not fully compensating, but it materially exceeds 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 names a concrete resource (a cash calendar of upcoming money in and out) and enumerates exactly what appears in it: bills, payroll, subscriptions, expected income, taxes, card/loan minimums, bucket schedules. That enumeration separates it cleanly from siblings like list_recurring, get_liabilities and query_transactions, which an agent could otherwise 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?

The scope ('next N days', a forward-looking cash calendar) implies when the tool is appropriate for planning, but there is no explicit when-to-use/when-not-to-use guidance and no named alternative such as list_recurring or get_liabilities for agents that want raw recurring definitions rather than a forecast.

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 cover safety (destructiveHint=false, idempotentHint=true), and the description adds real beyond-schema behavior: it never moves money, a mismatch surfaces as a fixable check, undo removes the pin, review mode yields 'pending_review', and duplicate detection returns possible_duplicates. The long generic write-tool block is shared boilerplate, so its marginal value for pin_balance specifically is diluted.

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 tool-specific content is front-loaded in the first paragraph, which is good, but it is then followed by a large block of generic 'how every write tool behaves' bullets that apply to all write tools and dominate the length. For a single tool definition this is heavy relative to the pin-specific content.

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

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

With an output schema present, return values need not be explained, and the description still covers mutation semantics, undo window, review flow, idempotency, and required company/whose-money inputs. Complete enough for correct invocation, only slightly repetitive against annotations.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description restates the card/loan balance sign convention ('amount owed, as a positive number'), which duplicates the schema's own balance description rather than adding new 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?

The opening sentence names the specific resource and its scope: a statement balance for one account on one day, checked against Aggregate's records without changing them. This is a clear verb-adjacent concept ('pin', with 'Undo removes the pin'), though it never explicitly distinguishes itself from the related sibling refresh_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 explicit when-to-use statement, and no comparison against alternatives like refresh_balance or add_entry. The guidance present is generic write-tool boilerplate about duplicates and linking via search_transactions/update_record, which is not tool-selection 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds behavior beyond that: the default exclusion of paid invoices with the specific statuses included, the two-group cap, and the per-currency measure semantics. It omits limit/pagination behavior and ordering defaults, but the added filtering context is substantive.

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?

Dense but front-loaded: purpose first, then grouping dimensions, measures, default filter, and a routing example. Every clause carries information, though the enum restatements make it feel packed and could be trimmed if the schema documented more.

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

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

For an 8-parameter, no-output-schema aggregation tool, the description supplies the grouping model, measure vocabulary, and default scope an agent needs to form a correct call. Remaining gaps (limit/pagination, ordering default rationale) are minor rather than blocking.

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

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

Schema description coverage is only 25%, so the description carries real weight: it defines the side values (owed_to_you = invoices you sent, you_owe = bills you received), enumerates the group_by dimensions with an aging breakdown, and lists the available measures. Undocumented remain limit, counterparty, and the ordering interaction, but it compensates well for the low 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?

Opens with a concrete verb and resource ('Adds up invoices you sent ... and bills you received ... grouped by'), and explicitly distinguishes itself from search_invoices ('search_invoices lists the invoices behind a group'). An agent can tell this is an aggregation tool versus a listing tool without opening either schema.

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

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

Gives a worked example ('who owes the most, by aging') and states the default filtering posture (only open/overdue/partially paid/disputed unless include_paid), which is real when-to-use guidance. It names the complementary sibling for drill-down, but does not state when a different aggregation tool (e.g. get_reports) would be preferable.

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/openWorld=false, so safety is covered; the description then adds substantial behavior beyond that: voided rows excluded, expected rows gated behind include_expected, payroll rows hidden for connections without payroll visibility (and those companies named), internal money movement excluded unless include_transfers is true, and currencies never summed together. This is exactly the kind of non-obvious scoping an agent needs to interpret totals.

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 purpose before the behavioral clauses, and each clause carries distinct information (grouping, measures, filters, exclusions). It is dense and long, but there is little filler; the length is justified by the tool's 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?

With 10 parameters, no required fields, and no output schema, the description does the heavy lifting on grouping, measures, and exclusion rules. The one residual gap is the exact shape of the returned groups (keys plus measure values), which the agent must infer, but the grouping/measure framing makes this largely predictable.

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

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

Schema coverage is 60%, and the description compensates well: it enumerates the group_by and measures options, defines week as starting Monday, clarifies that currencies are never added together, and explains what include_expected and include_transfers actually change. It adds real semantics beyond the enum values, though limit, order, and from/to handling remain mostly schema-only.

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 precise verb+resource+scope: it aggregates ('adds up') transactions matching a search, grouped by up to two dimensions. It explicitly differentiates from the sibling search_transactions by noting that a group can be opened with search_transactions to see its rows, so the agent can tell aggregation from row retrieval without opening either schema.

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

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

Clearly positions the tool against search_transactions (this returns grouped totals; that returns rows) and states the filter set is identical. It does not spell out an explicit 'use this instead of X when you want Y' exclusion, but the routing context is clear enough to choose correctly.

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

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

Annotations already establish readOnly=false, idempotent=true, destructive=false, but the description goes well beyond them: immediate apply with a 30-day undo window, review-mode 'pending_review' status, refusal when company/whose money is missing, duplicate detection returned as possible_duplicates, idempotency_key retry semantics, a prompt-injection warning about document text, and the scope limit that it never moves money. This is unusually rich behavioral disclosure.

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

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

Long, but justified by a 24-parameter, multi-event tool. Purpose and event mapping are front-loaded, then the shared write-behavior block is separated with bullets. Some of the generic write-tool boilerplate (bookkeeping meaning of Stripe payouts and card payments) is tangential to recording an equity event and could be trimmed.

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

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

An output schema exists and possible_duplicates/link suggestions are referenced, so return values need not be spelled out. Combined with annotations and the write-behavior block, the description is nearly complete for a complex tool; the only shortfall is that a handful of SAFE/note and transfer parameters are left to the schema alone.

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

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

With 24 parameters at 63% schema coverage, the description adds real meaning for the hardest-to-infer fields: grant_type usage across option_grant/exercise/cancellation, net_exercise paid in shares, withheld_shares for tax, amounts accepted in any currency, and the idempotency_key contract. It does not clarify the SAFE/note-specific fields (discount_pct, interest_pct, valuation_cap) or transfer fields like to_stakeholder, leaving a modest gap.

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

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

States a specific verb (record) and resource (equity event / cap table) and then enumerates exactly which event types belong here: issuance, SAFE, convertible note, option grant, exercise, transfer, cancellation. It maps ambiguous domain terms (RSU, warrant) onto this tool's parameters, so an agent can distinguish it from add_entry, add_invoice, or update_record without opening a schema.

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

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

Gives clear routing rules for representation (RSU -> option_grant with grant_type 'rsu'; warrant -> option_grant with grant_type 'warrant') and names sibling tools for the duplicate-linking workflow (search_transactions, search_invoices, update_record). It does not explicitly state when to prefer add_entry or void_record over this tool, so guidance is strong but not 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true): it discloses the 30-day undo window, the pending_review waiting state, duplicate detection within 7 days with possible_duplicates output, the hard requirement that company and whose-money are never inferred, idempotency_key replay behavior, and that it never moves money. It even flags third-party document text as data, not instructions.

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

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

The core purpose is front-loaded and the bulleted block is well organized, but a sizable portion is generic 'every write tool behaves' boilerplate that inflates length. Every sentence is relevant, yet the shared block reduces density for this specific tool.

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

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

For a 13-param write tool with a nested applications array, an output schema, and annotations, the description covers the money-flow semantics, review/undo behavior, duplicate and idempotency handling, and refusal conditions. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 62%, and the description compensates by explaining intent for key params: bank_transaction_id (link instead of double count), unapplied remainder becoming credit, and the non-inferable company/whose-money inputs. It does not cover method, counterparty, or source_document_id, so it adds real but incomplete 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?

Opens with a specific verb and resource plus the two semantic branches: 'Record that an invoice was paid (owed_to_you) or a bill was paid (you_owe), fully or partly, across one or more invoices.' Combined with the title, an agent can clearly distinguish this payment-application write from generic writes like add_entry or update_record.

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

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

Gives concrete routing conditions: pass bank_transaction_id when money already shows in the bank, use search_transactions/search_invoices to find duplicates, and link via update_record to avoid double counting. It stops short of explicit exclusion language ('do not use this for X, use add_entry instead'), so it is strong context but not a complete when/not map.

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

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

Annotations only mark it non-read-only/open-world/non-idempotent; the description goes far beyond by disclosing billing per bank connection, the confirm-gated dry-run vs execution behavior, per-connection cooldown and per-workspace daily limits, and the exact fallback (last known balances plus next allowed time) when a limit is hit.

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

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

Long but dense and front-loaded with the core action, then billing, then the confirm mechanic, then alternatives and limits. Every sentence carries distinct information, though the sentence length makes it slightly heavy to scan.

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

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

With no output schema, the description still explains what comes back in both branches (cost/connection preview vs fresh balances, and the limit-exhausted fallback payload). An agent needs nothing more 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 coverage is 100%, so the baseline is 3, but the description adds real behavioral meaning to confirm (false = nothing called, just a cost preview; true = check runs and fresh balances return) that the schema only states tersely, plus reinforcement of the account/company scoping.

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 ('Asks the bank for balances right now') and explicitly scopes it to connections that support live checks. It distinguishes itself from the sync-based alternatives (get_metric, list_accounts) that provide the same data for free.

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

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

Explicit when-to-use ('a live check matters only for "right now" questions'), when-not-to (daily balances already in get_metric/list_accounts at no cost), and names the alternatives. The cost gating via confirm also functions as usage guidance.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description adds substantial context beyond them: the pending_review status with approval_url, owner/admin approval requirement in review mode, a 30-day undo window, and idempotency_key retry semantics. For a destructive operation this is genuinely rich disclosure.

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 tool-specific first paragraph is well front-loaded and tight. However, the description then appends a large generic block ("How every write tool behaves") of ten bullets that is largely shared boilerplate, diluting focus and inflating length for a single-purpose operation.

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

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

An output schema exists, so return values need not be spelled out, yet the description still explains status/approval_url and undo behavior. Combined with owner/admin availability and idempotency handling, it covers what an agent needs for this destructive, approval-gated write.

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 reason, company, dry_run, and idempotency_key, making 3 the baseline. The description reinforces that company/whose-money are never inferred ("a write without them is refused") but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ("Removes a company's period lock") and immediately clarifies the effect (old dates post on their own dates again, closed reports can change). It is clearly distinguishable from the close_period sibling, which it references obliquely via "Undo closes the books again."

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 a precondition ("Available to connections made by owners and admins") and an inverse action ("Undo closes the books again"), which is useful context. However, it never explicitly states when to reopen vs. leave closed, nor routes the agent to a specific alternative, so usage is only implied.

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

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

Annotations declare a destructive, non-readonly, idempotent write, and the description adds substantial context beyond them: immediate application with 30-day undo, pending_review status under review mode, duplicate-detection heuristics (same amount ± fees, 7 days, same counterparty), required company/whose-money inputs that Aggregate refuses to infer, and an explicit statement that it never moves money or contacts anyone.

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 tool-specific opening paragraph is tight and front-loaded, but the appended 'how every write tool behaves' block is a long boilerplate list. Several bullets (bookkeeping meaning of bank deposits, Stripe payouts, card payments) are generic accounting background rather than guidance for invoking this specific tool, so not every sentence earns its place.

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

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

An output schema exists so return values need not be described, and the description covers the destructive/review/duplicate/idempotency behavior an agent needs. Minor gaps remain on how confirm vs reject affects the underlying row and on the reason field's role, but the definition is broadly sufficient for a 6-parameter write 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 67% and the description supplements it meaningfully: it explains idempotency_key retry semantics (same key returns the original record), shows the shape of edits for a which-company answer, and frames decision as confirm/reject/edit. The reason and dry_run fields are only covered by the schema, not the prose.

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

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

The first sentence names the exact verb set (confirm/reject/edit) and the exact resource (an item from list_review_items), then enumerates the item kinds (suggested match, possible duplicate, suggested rule, whose-money, which-company). An agent can distinguish this from siblings like update_record or void_record without opening any schema.

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

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

It names the upstream source (list_review_items) and gives a concrete usage rule for the which-company case with the exact edit payload. It also states an exclusion — AI changes held for review can only be approved by a person in Aggregate, not here — but does not contrast confirm vs reject vs edit or explain when to prefer this over directly calling update_record.

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 real value beyond that: an explicit prompt-injection warning that untrusted_text fields are third-party data, not instructions, and that "⚠ flagged text:" names are suspicious. It also enumerates returned fields and aging buckets and notes the concise-vs-detailed output tradeoff, though it says nothing about pagination behavior.

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

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

The key owed_to_you/you_owe split is front-loaded, which is good, but the first sentence is an overlong run-on enumerating status, totals and aging buckets that largely restate returned data. The safety note is well-placed at the end, but the middle budget spent on output fields costs clarity for an 11-parameter search 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?

With 11 optional params, no output schema, and nested amount object, the description does meaningful work: it defines the side semantics, sketches the return payload, and adds a prompt-injection caveat that no structured field carries. It stops short of explaining pagination (cursor/limit is only valid for single-side queries) and the response_format tradeoff beyond what the schema says.

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

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

Schema description coverage is only 45%, so the description is expected to compensate and partially does: it explains the side parameter's owed_to_you/you_owe semantics, which the schema enum does not define. But cursor, limit, response_format, due_before, overdue_days_min and the amount-tolerance filter are left to the schema, and the long field list describes outputs rather than the undocumented inputs.

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 (search) and resource (invoices/bills), and draws the owed_to_you vs you_owe distinction plus the field/aging-bucket coverage. It signals it is a lookup that precedes an add/pay action, which leans toward add_invoice. However it never names or distinguishes itself from the sibling query_invoices, which appears to be the closest alternative, so the differentiation is incomplete.

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?

"Finds the existing invoice or bill before one is added or paid" implies a use case (dedupe/verify before add_invoice or record_payment), which is genuine implied guidance. But there is no explicit when-not, and no routing between this tool and query_invoices or search_transactions. An agent must guess which of the two invoice-search tools to use.

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 mark it read-only, idempotent and non-destructive, yet the description adds substantial context beyond them: totals and sums computed across all pages, that raw memos are omitted unless include_raw_text, that rows indicate prior existence, and explicit prompt-injection handling for untrusted_text and flagged names.

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

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

The core purpose plus filter and return summary is front-loaded in the first sentence, and every subsequent sentence carries real information. It is dense but not padded, though the run-on enumeration of return fields is slightly sprawling.

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 17 parameters, the description carries the return-value burden and does so well, covering counterparty names, category, linkage, attribution and cross-page aggregates. Pagination mechanics are left to the cursor/limit schema descriptions, which is acceptable.

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

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

Schema coverage is only 47% across 17 parameters, so the description must compensate. It names most filter dimensions (company, account, dates, amounts, direction, category, counterparty, source, status) and explains include_raw_text, but leaves limit, cursor, response_format and needs_review to the schema, so it only partially fills the gap.

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

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

The description states a specific verb and resource ("Find transactions") and enumerates the filter dimensions it supports, so an agent knows exactly what it does. It does not differentiate itself from the near-identical sibling query_transactions, which is the one thing needed for 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?

Usage is implied through the query syntax and the note that the same query works in create_rule, giving some routing context. However, it never says when to prefer this over query_transactions or search_invoices, and gives no exclusions or prerequisites.

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

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

The write-policy block does add real context beyond the annotations: immediate application, 30-day undo, review-mode 'pending_review' staging, and idempotency semantics. However, most of it is copy-pasted boilerplate describing money/transaction writes (amount, currency, counterparty, bank syncs, Stripe payouts) that has no bearing on updating a bucket, so the relevant signal is diluted.

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 first two sentences are tight and front-loaded, but the following ten-bullet 'How every write tool behaves' block is largely irrelevant to bucket updating (duplicate money detection, bookkeeping meaning, third-party document text). A large share of the text does not earn its place in this 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?

An output schema exists, so return-format explanation is not needed, and mutation safety (undo, review, idempotency) is covered. What is missing is guidance on choosing this tool over create_bucket/update_record and coverage of the undocumented parameters, while the misplaced money-write boilerplate adds noise rather than completeness.

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

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

Schema description coverage is only 38%, so the description has to carry weight, and it does explain patch semantics, that null clears the schedule, and idempotency_key retry behavior. It says nothing about 'reason' or the required 'bucket_id', leaving a gap. Partial compensation only.

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

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

The opening sentence states a specific verb and resource plus the mutable surface: 'Rename a bucket or change its fields, values or schedule.' That distinguishes it from get_bucket/list_buckets/create_bucket, though it never names a sibling explicitly. Clear, but not sibling-differentiated.

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

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

It gives useful patch semantics ('Send only what changes; schedule null removes it'), which tells the agent how to call it, but nothing about when to choose it over create_bucket or update_record, and no exclusions. Usage is implied rather than stated.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: immediate application with a 30-day undo window, review-mode 'pending_review' pending state, refusal when company/whose-money are missing, idempotency_key retry semantics returning the original record, possible_duplicates feedback, and an explicit 'never moves money' limit. No statement contradicts the annotations.

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

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

The tool-specific opening is well front-loaded and tight, but roughly half the text is a generic 'How every write tool behaves' block duplicated across the write siblings, which inflates length without helping distinguish this tool. Sizing is defensible for the domain's complexity but not economical.

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

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

With an output schema present the description is not obligated to explain return values, yet it still notes that the result lists the record and suggested links. Combined with coverage of approval states, refusal conditions, duplicate logic, and safety scoping, an agent has everything needed to call this correctly.

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

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

Schema coverage is 60%, so the description must add meaning. It clarifies link_to semantics with a concrete reimbursement example, spells out paid_by values, and explains the immutability of bank-sourced amount/date fields and idempotency_key reuse. Some of this overlaps the schema's own link_to/paid_by/idempotency_key descriptions, so it does not fully compensate for the remaining undocumented gaps.

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 precise verb and resource plus an enumerated list of what can change (category, company, paid_by/for_company, note, linking), and explicitly states the negative constraint that bank-sourced amounts/dates cannot be changed. It also routes the agent toward search_transactions/search_invoices for duplicate discovery, distinguishing it from read 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?

Gives clear context for when linking applies (fixing double counting) and points to the sibling search tools used alongside it. However, it never explicitly contrasts update_record with add_entry (create) or void_record (cancel), leaving the 'when not to use' side 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 non-read-only, destructive, idempotent, and closed-world behavior, but the description adds substantial context beyond them: immediate application with 30-day undo, pending_review mode, idempotency-key retry semantics, duplicate detection, bookkeeping meaning, and that it never moves money or contacts anyone.

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

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

The core purpose and the synced-row exclusion are front-loaded and clear, but the description then carries a long generic 'How every write tool behaves' block. Many bullets are broadly applicable policy text rather than void_record-specific guidance, making the definition verbose for a four-parameter 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?

With an output schema present and annotations covering safety and idempotency, the description is largely complete: it explains reversibility, review mode, duplicate risks, and when not to use the tool. However, the generic write-tool rules mention company and whose money as required inputs even though they are not in this tool's schema, which could mildly mislead an agent.

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

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

Schema description coverage is 75%, and the schema already documents reason, dry_run, and idempotency_key. The description elaborates idempotency-key retry behavior and duplicate detection, but it does not explain the dry_run parameter and adds little for the bare id parameter, 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 ('Void a record') and scopes it to records added by hand or AI, such as mistaken or duplicate entries, invoices or buckets. It also distinguishes the tool from update_record by noting that synced bank rows cannot be voided.

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 void (hand/AI mistaken or duplicate entries) and when not to void synced bank rows, routing those to update_record instead. It also names search_transactions and search_invoices as tools for finding possible duplicates.

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, and openWorld=false, so the safety profile is covered. The description adds valuable scope: it enumerates what the response reveals (acting identity, visible companies, data kinds, write capability, source freshness, metric catalog), which goes beyond the annotations. It doesn't mention staleness of the identity cache or caching behavior.

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

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

Two sentences, front-loaded with 'Start here,' and dense with useful specifics. The second sentence is a long but justified enumeration of return contents; 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?

With no output schema, the description must convey what the tool returns, and it does so comprehensively: identity, scope, capabilities, freshness, metric catalog. For a zero-parameter discovery tool with annotations, this is nearly complete. It could mention the metric catalog's structure or format but is otherwise 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?

Zero parameters, so the baseline is 4. The description needn't explain inputs, and it correctly focuses on outputs.

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 purpose: returns the identity the connection acts for, its scope of access, capabilities, and metric catalog. This is clearly distinguishable from siblings like get_overview or get_activity, which fetch data rather than describe the connection itself.

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 opening 'Start here' is an explicit when-to-use directive, positioning this as the first call before other operations. No alternative tool serves this discovery purpose, so the guidance is complete.

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