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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds useful return behavior ('Returns the client with its id'), but it does not discuss duplicate handling, validation, required fields, or permissions.

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

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

The description is two short sentences, front-loaded with the operation and followed by the return behavior. There is no wasted text.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a six-parameter mutation tool with low schema description coverage, the description remains too sparse about parameter meaning and behavioral constraints.

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

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

Schema description coverage is only 17%, and the description mentions no parameters at all. With six parameters, only 'name' has a schema description, so the description does not compensate for the low coverage by explaining optional fields or defaults.

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 ('Add a new client'), making the core operation clear. It does not distinguish this from sibling tools like update_client, find_clients, or get_client, but the creation intent is unambiguous.

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

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

The description gives no guidance about when to use this tool versus alternatives such as update_client or find_clients, nor does it mention prerequisites or exclusions. Usage is only implied by the word 'Add'.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is known. The description adds genuinely new behavioral facts: the quote's status is mutated to accepted as a side effect, and the invoice inherits items and tax. It omits error behavior (e.g. what happens if the quote is already accepted) and whether repeated calls create duplicates.

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 sentence that front-loads the primary effect and uses the parenthetical efficiently to describe copied fields. No filler or redundancy.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. However, for a two-step conversion mutation the description leaves real gaps: the meaning of due_in_days and the behavior on an already-converted quote, both of which affect correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden for two parameters, yet it explains neither. quote_number is self-evident from its name, but due_in_days (a nullable integer with a null default) is completely unaddressed — an agent cannot tell from the description whether the invoice due date defaults, is required, or how it is computed.

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

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

The description names a specific verb pair and resource ('mark a quote as accepted and create the matching invoice'), which clearly distinguishes it from create_invoice or create_quote alone. The parenthetical '(same items and tax)' further pins down the copied data. It stops short of explicitly naming siblings like create_invoice as the from-scratch alternative.

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

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

Usage is only implied: an agent can infer this applies when an accepted quote should become an invoice, but there is no explicit statement of when to prefer this over set_quote_status plus create_invoice, nor any prerequisite (e.g. quote must exist / not already converted). No exclusions are 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 only declare that this is a non-destructive write with no open-world access; the description adds the important non-obvious fact that the result is a draft, not a sent invoice, which the annotations do not convey. It still says nothing about whether client_id must pre-exist or what errors occur on an unknown client, and the return value is covered by the output schema.

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

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

Two sentences, zero waste, with the draft-status constraint front-loaded ahead of the lifecycle pointer. Nothing could be removed without losing information.

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

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

The output schema and annotations carry the return value and safety profile, so the description does not need to. However, for a 6-parameter creation tool with only 50% schema coverage, it is thin: no mention of what client_id must reference, that items accept quantity/unit_price formats, or defaults for tax_rate, dates, and payment terms.

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

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

Schema description coverage is only 50% and the description adds no parameter meaning at all. Six parameters including required client_id, items, and notes are left entirely to the schema, and the description never compensates for the undocumented halves despite 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?

States a specific verb+resource ('Create a draft invoice') and immediately distinguishes it from the downstream sibling mark_invoice_sent. It does not differentiate from create_quote or convert_quote_to_invoice, which also produce invoice-like documents, so an agent must still infer when to build from a quote versus from scratch.

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 one clear sequencing rule: use mark_invoice_sent once the invoice has gone to the client, which implies this tool creates the pre-send state. It provides no exclusions or alternatives for the other invoice-producing siblings (convert_quote_to_invoice), so guidance is implied rather than complete.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds useful behavioral context that totals and tax are computed server-side, but it omits status defaults, permission requirements, and what happens to the created quote afterward.

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

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

Two short sentences with no filler, and the core action is front-loaded. The second sentence earns its place by noting automatic calculation, though the overall brevity leaves gaps rather than excess.

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

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

The presence of an output schema excuses explaining return values, but for a 5-parameter mutation with 40% parameter coverage and no status/validation context, the description is too thin. An agent would not know whether client_id must reference an existing client or what defaults apply to the quote's validity.

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 40%, so the description should compensate but does not. It says nothing about client_id, notes, items, valid_days, or the interaction between tax_rate and the profile default, leaving key parameters documented only partially or not at all.

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

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

The description gives a specific verb and resource ('Create a quote') and clarifies the synonym ('estimate'), so the core action is unambiguous. It does not, however, distinguish this from sibling tools like create_invoice or convert_quote_to_invoice, leaving the agent to infer the boundary.

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

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

There is no guidance on when to create a quote versus when to use create_invoice or convert_quote_to_invoice, nor any mention of prerequisites such as the client already existing. Usage is only implied by the tool name.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description nonetheless adds meaningful reassurance specific to the email domain — 'nothing is sent' — which preempts the common agent assumption that a reminder-email tool triggers delivery. It still does not say whether the draft is persisted anywhere or returned only as 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?

Two short sentences, front-loaded with the action and followed immediately by the most important constraint. No filler, no restatement of the tool name.

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-value explanation is not required. However, for a drafting tool with an unexplained tone enum and a 0%-covered schema, the description leaves open what 'final' tone implies and how the produced draft relates to the send workflow — gaps an agent would notice.

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

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

Schema description coverage is 0% and the description never mentions either parameter. The 'tone' parameter in particular (friendly/firm/final) carries real semantics — escalation level and likely wording intensity — that the enum values alone do not explain, and the description does nothing to compensate.

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 artifact (write a payment-reminder email) plus the target object (an unpaid invoice), so the agent knows exactly what is produced. The 'Draft only: nothing is sent' clause separates it in spirit from mark_invoice_sent, but no sibling is named and 'unpaid' preconditioning is only implied by the tool name.

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

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

Usage is implied by the phrase 'for an unpaid invoice', which tells the agent the precondition, but there is no explicit when-to-use versus when-not guidance. Siblings like overdue_report (identifying which invoices are late) and mark_invoice_sent (actually sending) are not referenced, so the agent must infer the workflow split.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is pre-supplied. The description adds that a file artifact is created and that its location is returned — useful context — but says nothing about where the file is written, whether an existing file is overwritten, or that a persistent artifact is produced despite the readOnly hint; the return value itself is covered by the output schema.

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

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

One tight, front-loaded sentence with no filler, and the outcome (where it was saved) is placed after the action. It is efficient but has no structure beyond the single 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?

The tool is simple, the parameter is fully documented, and an output schema covers the return value, so the description is nearly adequate. It nonetheless leaves out the one behavioral fact an agent would want — that a file is written to disk and where — which matters for a tool annotated as read-only.

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 parameter is documented as 'Quote or invoice number', which the description merely restates. With one fully-documented parameter, baseline 3 applies; the description adds no format, lookup, or disambiguation detail.

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

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

The description names a specific verb and artifact ('Save ... as a PDF file') plus the two document types it handles (quote or invoice), so it is clearly distinct from read-oriented siblings like get_document or list_invoices. It does not explicitly name any sibling as an alternative, which keeps it below a 5.

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

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

Usage is only implied: an agent can infer 'call this when you need a downloadable PDF of a quote or invoice', but there is no statement of when to prefer this over get_document or list_invoices, no prerequisites, and no exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context that results carry financial aggregates, but says nothing about the default 20-record cap, result ordering, or whether the totals are lifetime or date-bounded.

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 compact sentence with the resource up front and the returned data stated immediately. No filler, though it is so terse that it omits selection guidance the agent needs.

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

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

An output schema exists, so return values needn't be spelled out, and the read-only nature is covered by annotations. What remains missing for a search tool in a 20-sibling set is the routing guidance against get_client/list_invoices and any hint about the result cap.

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

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

Schema coverage is only 50%: query is well documented ('Part of a name, company or email. Empty lists everyone.') but limit has no description anywhere. The description contributes nothing about either parameter and so fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Search clients') and adds the distinguishing payload: per-client invoiced, paid and outstanding totals. It does not explicitly distinguish itself from sibling get_client or list_invoices, but the aggregation angle is clear enough to select on.

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 and no mention of alternatives. Nothing tells the agent whether to use this versus get_client for a single client or list_invoices for document-level data; the search semantics are only implied by the verb.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds that the profile is the one appearing on quotes and invoices, which gives useful domain context, but it says nothing about permissions, defaults if unset, or behavior of the returned terms/currency values.

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 the resource named first and the field enumeration compact. Zero filler and nothing an agent must skip over.

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

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

A zero-argument read tool with an output schema and read-only annotations is nearly self-describing, and the description covers the only open question — what the profile contains. It stops short of noting whether fields can be empty or how the profile relates to document generation beyond a passing mention.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly does not invent parameters and its field list instead describes payload content, which is harmless context.

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 ('Show') plus resource ('business profile') with a parenthetical enumerating the fields returned (name, currency, tax rate, terms), so the agent knows exactly what this retrieves. It does not explicitly name the sibling update_business_profile as the mutation counterpart, but the read/mutate pairing is inferable from the name.

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

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

The phrase 'used on quotes and invoices' implies the context in which this profile matters, but there is no explicit when-to-use, when-not-to-use, or routing to update_business_profile. For a simple no-argument read, that implied framing is adequate but not instructive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the response includes balances, which is meaningful beyond the annotations, but it doesn't say what 'full details' encompasses or how a missing/unknown client_id is handled.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity borders on under-specification for a lookup tool with an undocumented identifier parameter.

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

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

An output schema exists, so return shape needn't be explained, and read-only behavior is annotated. However, for a single-record lookup an agent still needs to know where client_id comes from and what happens on a bad id, and neither is covered.

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% for the single required client_id, so the description must compensate; 'one client' only implies the parameter is a single identifier without specifying format, integer semantics, or source (e.g., from find_clients). A minimal but nonzero contribution.

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 ('get_client') and scope ('Full details and balances for one client'), which implicitly contrasts with the list/search sibling find_clients. It does not explicitly name find_clients, so the distinction is inferred rather than stated.

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

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

Usage is only implied: 'one client' signals this is a single-record lookup keyed by an id, versus a search. There is no explicit when-to-use/when-not guidance, no mention of what to do when the id is unknown (e.g., call find_clients first), and no error-condition guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered by structured data. The description contributes the kind of content returned (payments, balance, overdue days), but says nothing about not-found behavior or what happens when the number matches no document — a modest addition 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?

A single front-loaded sentence with zero filler; the scope and the returned content are both packed into one clause without repetition.

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

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

For a one-parameter read with full schema coverage and an output schema in place, the description is essentially sufficient — the agent knows what it gets back. Minor gap: it never states behavior for an unknown or non-existent document number.

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 'number' parameter is documented with an example (INV-0007), so the schema carries the load. The description only implies the input is a quote-or-invoice number via 'one quote or invoice' and adds no format or matching rules beyond the schema.

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

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

The description uses a specific resource ('one quote or invoice') and enumerates the payload (items, totals, payments, balance, overdue days), which clearly separates it from the list_* siblings. It lacks an explicit verb ('retrieve/fetch') but the intent is unambiguous, and the 'one' framing distinguishes it from batch tools.

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

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

Usage is only implied: an agent can infer this is the tool for pulling full detail on a single document, but there is no statement of when to prefer it over list_invoices, list_quotes, or overdue_report, and no prerequisites or exclusions are 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?

The annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds ordering ('newest first') but does not mention pagination behavior, default limit handling, or permissions, leaving some behavioral context unstated.

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

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

The description is a single front-loaded sentence with no wasted words. Every clause earns its place by adding ordering or filter 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?

The tool is low-complexity and has an output schema plus read-only annotations, so return values need not be explained. However, with 0% schema description coverage and four parameters, the description leaves limit undocumented and does not clarify status values, so it is only minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate. It names three of the four filters but omits the limit parameter and does not enumerate valid status values, leaving meaningful gaps despite the useful filter names.

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 (list invoices) plus ordering and filter options. It is clear, but it does not explicitly distinguish this tool from siblings such as overdue_report or list_quotes.

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

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

Usage is implied by the mention of optional status/client/overdue filters, but there is no explicit guidance on when to use this versus overdue_report or export_pdf. The agent must infer the scenario.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are ordered newest first — but omits default page size, pagination behavior, and what happens when filters are omitted.

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

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

A single short sentence with zero wasted words, and the ordering constraint is front-loaded. It is efficient, though its terseness borders on under-specification rather than optimal conciseness.

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

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

An output schema exists, so return values need not be explained. However, for a three-parameter listing tool with 0% parameter documentation, the description should describe the filters and default limit; as written, an agent cannot confidently use status or client_id filtering.

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

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

All three parameters (limit, status, client_id) have 0% schema description coverage and none are mentioned in the description. The agent has no documented meaning for status values or client_id beyond the enum/type, so the description completely fails to compensate for the coverage gap.

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

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

States a clear verb+resource combination ('List quotes') and adds the ordering ('newest first'), so an agent knows exactly what it returns. It does not differentiate from siblings such as list_invoices or explain how it relates to get_document, leaving that inference to the agent.

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 or when-not-to-use guidance, no mention of alternatives, and no prerequisites. The description only implies usage through its name; an agent must guess how it differs from get_document or list_invoices.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuine value by disclosing the state-transition consequence that the invoice begins counting toward overdue reports. It does not cover idempotency (what happens if the invoice is already marked sent) or failure behavior for a non-existent invoice number.

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

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

One sentence, front-loaded with the action, with a parenthetical that earns its place by explaining the downstream effect. 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. For a simple single-parameter state-change tool, the key behavioral consequence is disclosed; only edge-case behavior (repeat calls, invalid invoice) is missing.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter, and it does not mention invoice_number at all. The parameter name and schema title make its meaning largely self-evident, so the practical gap is small, but no format or constraint guidance (e.g., expected invoice number format) is provided.

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 ('Record that an invoice was sent to the client'), which is clearly distinct from siblings like record_payment or void_invoice. It stops short of explicitly differentiating from relatives such as get_document or list_invoices, but the action 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?

Usage is implied by the parenthetical ('it then counts towards overdue reports'), which tells the agent the side effect of calling it. There is no explicit statement of when not to use it, no mention of prerequisites (e.g., the invoice must already exist), and no named alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and access profile are covered. The description adds useful behavioral detail by specifying the exact aging buckets used for grouping, which is beyond 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 description is a single, front-loaded sentence with no wasted words. It immediately states the core question the report answers and the grouping buckets.

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?

This is a simple read-only report with one optional, fully documented parameter and an output schema, so return values need not be explained in the description. The description supplies the remaining key context: what the report groups and how.

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

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

Schema description coverage is 100%, with as_of fully documented in the schema as YYYY-MM-DD defaulting to today. The description does not add any parameter meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly identifies the resource and behavior: money owed past the due date, grouped into aging buckets. It is easy to distinguish from most siblings, though it does not explicitly name alternatives such as revenue_report or list_invoices.

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

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

The description implies when to use the tool by framing it as an overdue aging report, but it provides no explicit when-to-use guidance or comparison with related tools. An agent can infer the purpose, but routing against siblings like revenue_report or list_invoices is left to context.

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

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

Annotations already establish that this is a read-only, closed-world operation. The description adds useful context about the returned content, but it does not explain recency, ordering, pagination, or how the limit affects results.

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

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

The description is a single front-loaded sentence with no wasted wording. It is appropriately concise, though its brevity contributes to gaps covered in other dimensions.

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 and clear read-only annotations, the description does not need to explain return values in detail. However, it leaves important context undefined, including what 'recent' means and how the optional limit affects the result.

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

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

The schema has one parameter, limit, with 0% description coverage and a default of 20. The description never mentions the parameter or explains how it controls the amount of activity returned.

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 clearly identifies the resource as an audit log and says it reports what changed and when. It lacks an explicit verb and does not distinguish itself from siblings, but the purpose is still understandable.

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

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

There is no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The intended use is only implied by the name and the phrase 'audit log'.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds one genuinely useful behavioral rule — overpayments are rejected — but says nothing about partial payments, duplicate submissions, idempotency, whether the invoice status changes, or what error is raised on refusal.

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 action and followed by the most important constraint. Nothing is padded or 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?

An output schema exists, so return values need not be explained, and annotations cover the write/read profile. However, for a financial mutation tool the description omits material behavior: how partial payments interact with the invoice, what happens on repeat submission, and what the refusal condition actually is beyond 'overpayment'.

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 60% (reference and invoice_number have no descriptions), so the description should compensate, and it does not — it mentions no parameter at all. The overpayment rule implicitly constrains 'amount' relative to the invoice balance but never states that relationship explicitly.

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 ('Record money received against an invoice'), which is immediately actionable. No sibling tool records payments, so there is little to disambiguate, though it never explicitly differentiates itself from adjacent tools like get_document or list_invoices.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites such as the invoice needing to exist or be in a particular status, and no alternatives named. The only constraint given ('Overpayments are refused') is a rejection rule, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely useful data-scope rule — drafts and voids are excluded from invoiced figures — which an agent could not infer otherwise. It says nothing about computation timing, currency handling, or authorization needs.

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 terse sentence with zero waste, leading with the primary metric pair before the secondary ones. It is a noun-phrase list rather than a verb-led statement, which slightly slows comprehension but costs no length.

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 full parameter documentation, the description only needs to convey what the report contains and its data-scope rules, which it does. The exclusion note and metric inventory are the key facts; minor gaps around default range behavior are already covered by the schema.

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

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

Schema description coverage is 100%, with both start and end documented including format and defaults, so the schema carries parameter meaning fully. The description adds no additional semantics about the date range or how it affects the monthly buckets.

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 specific metrics produced (invoiced vs collected by month, outstanding balance, top clients) and scopes the data with exclusions, so it is clearly a revenue analytics report. It never explicitly distinguishes itself from siblings like overdue_report, which also touches outstanding money.

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

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

There is no guidance on when to pick this over overdue_report or recent_activity, and no mention of prerequisites or typical use cases. The reader must infer from the metric list that this is the month-by-month financial rollup.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say whether the write is idempotent, whether transitions are reversible (accepted back to sent), or whether setting a status has side effects such as locking the quote.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though the brevity borders on under-specification for a state-mutating tool rather than true conciseness.

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

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

An output schema exists, so return values need no explanation, and the status enum is self-documenting. However, for a state-transition tool the description omits preconditions, reversibility, and side effects that an agent needs before invoking it.

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

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

Schema description coverage is 0%, so the description must carry the load, yet it only restates the three status values the enum already declares. The quote_number parameter — its format and where to obtain it — is completely unexplained in both schema and description.

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 ('Record ... quote status') and enumerates the three permitted statuses, so the operation is unambiguous. It does not distinguish itself from siblings like create_quote or convert_quote_to_invoice, which also touch quote state.

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

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

No guidance on when to use this versus siblings such as create_quote, convert_quote_to_invoice, or list_quotes. Preconditions (must the quote already exist?) and whether a status can be re-set/rolled back are left entirely 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=false, destructiveHint=false and openWorldHint=false, so the safety profile is known. The description adds a real behavioral trait beyond that: omitted fields are left untouched (merge semantics, not overwrite). It does not mention permission requirements, whether changing tax_id/currency affects existing invoices/quotes, or what is returned.

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

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

Two short sentences, zero waste, with the mutation semantics front-loaded right after the action statement. Nothing is repeated from the schema or annotations.

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

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

The output schema exists, so return values need not be explained, and annotations cover the read/write profile. However, for a 10-param settings mutation with 30% schema coverage, the description leaves gaps: no field range, no note on side effects to existing documents, and no prerequisite/permission context.

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 30% (only currency, default_tax_rate and payment_instructions are documented), so the description should compensate more than it does. It does cover the single most important semantic for all 10 optional nullable params — that passing nothing is a no-op and nulls are not written — but says nothing about units/formats for quote_valid_days, payment_terms_days, tax_id, or address.

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 ('Change business details'), which clearly distinguishes it from the read-side sibling get_business_profile. It is clear but does not list the editable field domain, so an agent must open the schema to learn what 'business details' covers.

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 usage via the partial-update note but gives no explicit when-to-use/when-not guidance and names no alternative (e.g., get_business_profile for reading). An agent must infer that this is the write counterpart to get_business_profile from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description usefully adds the partial-update contract, but leaves a critical ambiguity for a tool where every field defaults to null: whether passing an explicit null clears a field or is ignored, and what happens if client_id does not exist.

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

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

Two short sentences with zero filler, and the operation is stated before the caveat. Sizing is aggressive but nothing is wasted; the terseness is penalized under contextual completeness rather than 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?

An output schema exists, so return values need no explanation. However, a seven-parameter mutation with 0% schema coverage and no annotations on error behavior needs more: which fields are editable, null semantics, whether client_id must reference an existing client, and what a partial failure looks like.

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 carries the full burden, and it names none of the seven parameters or the six updatable fields (name, email, notes, phone, address, company). The only added meaning is the omit-to-keep behavior, which leaves the null-vs-absent distinction for nullable fields unexplained.

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

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

"Change a client's details" gives a clear verb plus resource, and the second sentence narrows the operation to a partial update. It does not explicitly distinguish itself from siblings like add_client or update_business_profile, but the resource (client vs. business profile) makes the distinction inferable from the name.

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

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

"Only the fields you pass are changed" implies the patch-style usage pattern and signals that this is an edit rather than a read, but no conditions for choosing it over siblings (e.g., get_client first, or find_clients to obtain the client_id) are stated. Usage is implied rather than guided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: this is a soft void rather than a delete ('the record is kept') and the supplied reason is persisted. It omits whether a void can be reversed or what happens on failure, leaving a small gap.

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

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

Two short sentences with no filler, and the eligibility constraint is front-loaded before the persistence note. Every sentence contributes distinct 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 annotations covering the destructive profile and an output schema available for return values, the description only needs to justify the operation and its precondition, which it does. Missing permission requirements and reversibility semantics are minor but real gaps for a destructive operation.

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 must carry parameter meaning. 'The record is kept with the reason' explains why the reason argument matters, but invoice_number is not addressed at all and no format or validation detail is given for either parameter.

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

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

The description uses a specific verb and resource ('Cancel an invoice') and adds a distinguishing precondition ('that has no payments') that separates it from sibling tools like mark_invoice_sent or create_invoice. It stops short of explicitly naming an alternative for the case where payments exist, so it is clear but not sibling-differentiated by name.

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

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

The phrase 'that has no payments' gives an explicit eligibility condition, effectively telling the agent when this tool applies and when it does not. It does not point to a different tool for invoices that already have payments, so the routing guidance is implied rather than complete.

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