quote-template

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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

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

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential information.

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

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

For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent 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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present 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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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

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

The description begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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 explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

The description discloses key behavioral traits beyond the annotations: it states that numbers are copied and never recomputed, and explains the dual outcome (direct invoice creation vs. returning line items). These details align with the annotations (readOnlyHint false, destructiveHint false) and add meaningful context about state changes and accuracy guarantees.

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

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

The description is two sentences, front-loaded with the core purpose and then providing a critical behavioral detail. Every word earns its place, with no fluff or repetition of schema content. The structure is clean and immediately informative.

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 description explains the two possible outcomes (invoice creation or line items) and the crucial accuracy guarantee, which is essential for correct invocation. It does not explicitly cover the allow_expired parameter's behavior, but that is fully described in the schema. Given the tool's moderate complexity and high schema coverage, the description is sufficiently complete, though it could briefly mention the idempotency or lack thereof.

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 fully documents all five parameters. The description adds a general behavioral note ('numbers are copied, never recomputed') but does not enrich any specific parameter semantics beyond what the schema already provides. Baseline 3 is appropriate given the high 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 opens with a specific verb and resource ('Mark a quote accepted and turn it into an invoice'), clearly stating the tool's primary function. It also differentiates from siblings like quote_decline and quote_delete by focusing on the acceptance-to-invoice transformation, making the purpose 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 implies when to use the tool (to accept a quote and produce an invoice) and clarifies the conditional behavior based on the invoice store's presence. However, it does not explicitly contrast with alternatives or state when not to use it, though the conditional logic provides practical 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 declare readOnlyHint=false, which the description's 'Store a quote' aligns with, so there is no contradiction. The description adds value by disclosing the return payload (Q number, VAT, totals), shared-profile sourcing of currency/VAT/issuer, duplicate refusal, and the 5-open free-tier cap. However, the wrong MAJOR-units claim actively misdiscloses behavior and undermines transparency.

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

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

Three sentences with the purpose front-loaded and the constraints (duplicate refusal, 5-open limit, shared-profile defaults) stated efficiently. Only the erroneous unit sentence fails to earn its place, otherwise the description is tight and well-structured.

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

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

For a 12-parameter creation tool with no output schema, the description covers the key return values, defaults sourcing, and failure conditions, which is reasonably complete. It lacks details on error behavior and authentication, and the unit contradiction is a real completeness gap that could cause incorrect tool 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 100% with excellent parameter documentation (e.g., unit_price_minor '9000 = 90.00 EUR... Never a decimal'), so the baseline is 3. The description does not add value here; it actively harms by asserting unit_price is in MAJOR units, contradicting the schema's MINOR-unit definition for the same field. This negative contribution pulls the score below baseline.

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

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

The description states a clear verb+resource ('Store a quote... return its Q number, VAT and totals') and distinguishes itself from siblings like quote_update, quote_get, and quote_list by focusing on creation with an output. However, it muddies the purpose by claiming 'unit_price is in MAJOR units' when the actual parameter unit_price_minor is in MINOR units per the schema, which could mislead an 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?

The description provides useful usage constraints ('A duplicate of an open quote is refused. Free: 5 open.') that tell an agent when creation may fail, but it offers no explicit when-to-use vs alternatives guidance or exclusions. Sibling differentiation is left entirely to tool names rather than the description.

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 signal this is a write operation (readOnlyHint=false), and the description adds meaningful side effects: freeing an open slot, counting in the win rate, and keeping the reason on the record. The confusing accepted-quote sentence and lack of detail about reversibility or idempotency keep this from being 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?

The description is relatively compact and front-loads the primary action and consequences. The billing note 'Free on every tier' is somewhat extraneous Cert final response: concise JSON with 3 sentences + ambiguous secondary note, but the tool description is not bloated.

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

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

For a mutating tool with no output schema, the description covers the main effect and two meaningful business side effects among slot and win rate. It does not clarify the accepted-quote edge case, recoverability, or idempotency behavior, leaving an agent to guess in less common scenarios.

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 are already documented clearly, including the reason being kept on the record and the default date. The description adds no meaningful parameter semantics beyond what the schema already provides.

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

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

The description clearly identifies the tool as 'Mark a quote lost' and adds relevant consequences such as freeing a free-tier slot and affecting win rate. However, the sentence 'An accepted quote is refused, naming the invoice it became' is ambiguous and does not clearly distinguish this tool from quote_accept or quote_update.

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 this is for marking quotes as lost alternatives to quote_accept, quote_delete, or quote_update. It gives no explicit when-to-use or when-not-to-use guidance, leaving comparison with sibling tools 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 destructiveHint=true, and the description adds valuable behavioral context: the deleted quote's slot is freed, the id is never reissued, and quotes with dependent states are refused with the dependent named. This meaningfully augments the annotation without contradicting 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?

Two dense sentences; the first states the action and eligibility, the second covers failure behavior and id policy. Every clause earns its place and the key usage condition is front-loaded.

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

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

For a one-parameter destructive delete operation with no output schema, the description covers what can be deleted, what causes refusal, and the consequence of deletion. Nothing critical is missing for an agent to invoke the tool correctly.

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

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

The input schema already documents the single id parameter with 100% coverage, including an example format. The description adds little beyond the schema for parameter semantics, though the note that the id is never reissued gives slight extra context about id behavior.

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

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

The description states a specific action ('Delete') and a specific resource ('a draft quote') with precise eligibility conditions. It clearly distinguishes this tool from siblings like quote_decline and quote_update by focusing only on deletion of never-sent draft 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?

The description explicitly says when to use the tool: for draft quotes that were never sent, accepted, invoiced, or exported. It also explains when the tool will refuse and that a dependent will be named, which serves as a when-not signal, though it does not explicitly name an alternative sibling tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful return-level transparency: lines, VAT, totals, dates, current state with days left, notes, and the accepted invoice linkage. No contradiction with 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 that packs every important detail into one list. Each clause earns its place, and there is no filler or repetition.

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

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

For a one-parameter read tool with no output schema, this description is complete: it explains the input and enumerates the returned quote contents, including dynamic state and downstream invoice linkage. Nothing critical is missing.

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

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

Schema coverage is 100% and the description mirrors the schema's id meaning: Q number or exact client name. It adds no new format or behavior detail beyond what the input schema already documents.

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: 'Return one quote in full'. It also gives the lookup key (Q number or exact client name), and the singular 'one quote' distinguishes it from quote_list and other siblings.

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

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

The description makes the use case clear: retrieve complete details for a single known quote. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough for an agent to select it over list/pdf/report siblings.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: results are sorted newest first, the returned state is computed against today's date, and lapsed quotes appear as expired.

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, well-structured sentence front-loads the core purpose and output fields, then adds one crucial state nuance. Every clause earns its place.

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

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

With no output schema, the description covers the main return fields and state semantics. It does not mention pagination or response shape, but for a list tool with fully documented optional filters, the essential context is present.

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

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

Schema description coverage is 100%, so the parameter meanings are fully documented in the schema. The description adds no param-specific detail beyond the state-evaluation nuance, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List quotes'), the ordering ('newest first'), and enumerates the returned fields. It is clearly a collection-listing operation, though it does not explicitly differentiate itself from siblings like quote_get or quote_report.

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 is given about when to choose quote_list over sibling tools such as quote_get, quote_report, or quote_send_text. The listing intent is implied, but there are no explicit conditions or exclusions.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context by disclosing that the result is a download link valid for one hour and by describing the rendered document's contents. No contradiction exists between the description and 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 main description is a single, front-loaded sentence containing the essential facts: what to call, what it produces, and the link expiry. The trailing 'Pro.' fragment is unexplained and does not earn its place, but it does not seriously impair comprehension.

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

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

For a simple read-only tool with both parameters documented in the schema, the description adequately covers the output format, content, and link expiry. The odd 'Pro.' suffix introduces slight ambiguity about a possible access requirement, and there is no explicit note on error behavior, so it is not quite a 5.

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

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

Schema coverage is 100%, so the schema already documents id and out_path. The description's 'return a download link valid for one hour' largely echoes the out_path schema description rather than adding new parameter-level meaning, so it stays at the baseline.

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

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

The description starts with a direct command: 'Call this tool to render one quote as an A4 print-ready document', clearly naming the verb, resource, and deliverable. It also specifies the output contents (invoice layout, validity date, acceptance block) and the one-hour download link, which distinguishes it from siblings like quote_get, quote_list, or quote_report.

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 'Call this tool to render one quote...' gives an explicit trigger, and the PDF-specific language implies it is for print/download use rather than retrieval or acceptance workflows. It stops short of naming alternatives or stating when not to use it, so it is clear but not fully exclusive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful nuance about plan-dependent date handling (Free = current YTD, Pro = any range) and specifies the output dimensions. No contradiction.

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

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

Two tight, information-dense sentences with zero filler. Front-loads the report's core output and then adds the plan constraint. 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?

Even without an output schema, the description conveys the main result dimensions (per-currency totals by status, counts, open value, win rate) and the date-range policy. Minor gaps remain around exact win-rate definition and output formatting, but these are acceptable for a read-only report annotated as safe.

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

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

Schema coverage is 100%, so the schema already documents both optional date parameters. The description adds context that date-range filtering depends on the plan, but it doesn't clarify defaults or behavior when from/to are omitted. 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 exactly what the tool computes: totals per currency for open, accepted, declined, and expired quotes, along with counts, open value, and win rate. This clearly differentiates it from sibling tools like quote_list or quote_get, which return individual quote records.

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 makes it clear that this is an aggregate reporting tool, so an agent can infer when to use it. However, it never explicitly mentions alternatives or says 'use quote_list for raw data.' The Free/Pro date-range policy is useful context but is plan behavior rather than 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?

With all annotations false, the description carries the full behavioral burden. It discloses that output includes a .txt download link valid for one hour and notes that the tool is free, which covers the key temporal and cost-related behaviors an agent must know.

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

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

The description is two sentences with no filler: the first states the core deliverable, the second adds the download link expiry, cost, and sibling alternative. Every phrase 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?

Given there is no output schema, the description adequately explains what the tool returns (email-ready summary content and an expiring download link) and differentiates it from quote_pdf. Minor omissions like error handling or exact naming conventions do not impede 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 100%, so the schema already fully documents id, greeting, and sign_off. The description adds no parameter-level detail, which aligns with the baseline of 3 for high 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 names a specific action ('turn a quote into a plain-text summary'), enumerates the output elements (line table, VAT lines, total, validity date), and explicitly contrasts with quote_pdf, making its purpose unambiguous and distinguishable from siblings.

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

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

The description clearly implies when to use it (when a paste-ready plain-text quote for email is needed) and names the alternative quote_pdf for A4 documents. It does not explicitly state 'when not to use', but the sibling comparison provides sufficient 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds valuable behavioral context: totals are recomputed, and accepted/declined quotes are never edited. It also implies the tool mutates the quote. It doesn't mention whether the operation is reversible or requires permissions, but the key behavioral traits 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 sentences, front-loaded with the action and scope, followed by a critical behavioral constraint. Every sentence earns its place; no filler.

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

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

For a mutation tool with 11 parameters and no output schema, the description is fairly complete: it states what can be edited, the state constraint, and the recomputation behavior. It doesn't mention error cases (e.g., what happens if the quote is already accepted) or whether partial updates are allowed, but the core information an agent needs to decide to call it is present.

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

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

Schema description coverage is 45%, so the description partially compensates by listing the editable fields (line items, currency, discount, VAT default, validity, notes). It doesn't explain each parameter in detail, but the schema already covers many. The description adds the semantic context that these fields are the editable set and that totals are recomputed, which helps an agent understand the effect of changing them.

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 ('Revise') and resource ('a quote that is still open'), and enumerates the editable fields. It also explicitly distinguishes the tool from quote_accept and quote_decline by stating that accepted or declined quotes are never edited. This clearly differentiates it from siblings.

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

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

The description clearly indicates when to use this tool: when a quote is still open and needs revision. It also gives an exclusion: accepted or declined quotes are never edited, which implies using quote_accept or quote_decline for those states. It doesn't explicitly name alternatives, but the exclusion is strong enough guidance.

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