Make Parts Now: 3D Printing & CNC Machining Quotes

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

Annotations declare the safety profile (readOnly=false, idempotent=false, openWorld=true), but the description adds two things annotations cannot: that accept_terms must be true or the call fails, and that the api_key is shown only once (non-recoverable). That is meaningful behavioral context beyond the structured fields.

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

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

Three short sentences, front-loaded with the core action and the hard gating requirement, then the address shape and the one-time key. Efficient, though the ship_to restatement duplicates the schema rather than earning its place.

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

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

An output schema exists so return values need not be explained, and the description covers the critical validation and one-time-secret behavior. It omits prerequisites (no existing account required?), webhook/callback expectations, and how to recover or rotate the key, which would fully round it out.

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 description's parameter text (accept_terms requirement, ship_to object shape) is verbatim-equivalent to the schema descriptions. It adds no syntax, constraint, or default information the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an autonomous agent account and API key'), which clearly separates it from read-oriented siblings like get_account and from order-flow tools like create_checkout_link. It does not explicitly name or contrast with any sibling, so it stops short of a 5.

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

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

Usage is only implied: the tool is evidently the onboarding step that must precede order/quote tools, but the description never says when to call it versus get_account or what the prerequisite state is. No exclusions or alternatives 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 already flag destructiveHint=true, but the description earns credit for explaining what that destruction actually is: 'Each new link stops earlier links for the same quote from working.' That is real behavioral detail an agent cannot infer from the flags alone. It still omits auth/permission requirements and any rate-limit behavior.

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

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

Two short sentences, front-loaded with what the tool returns, and the invalidation warning placed immediately after. 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 described, and the annotations cover the safety profile. Combined with the explicit link-invalidation disclosure, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, and the schema already documents quote_id (qt_... from create_quote) and the idempotency_key retry semantics. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('get a Stripe Checkout URL') plus the audience (a human paying by card) and an outcome detail (tax added at checkout). The 'Option A' framing signals it is one of several payment paths, which separates it from the crypto path without naming it outright.

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?

'Option A' implies a counterpart option (likely pay_with_crypto) but never names or describes it, and there is no explicit when-to-use/when-not guidance. The tax note is a small piece of context but not routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered structurally. The description adds what the call yields (prices, speed options with ship/arrival dates, next_steps), which is useful, but says nothing about auth requirements, whether the quote is persisted for later checkout, or costs (rush fees are only noted in the schema). There is a mild tension between idempotentHint=false and the presence of an idempotency_key retry mechanism, though the description itself does not contradict the annotation.

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

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

Front-loaded with the verb+resource in three words, followed by a compact item/config sketch and a short return summary. Dense but every clause carries information; no filler sentences.

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

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

With an output schema present, the description needn't detail return values, and annotations cover the safety profile. It supplies the payload shape and the get_capabilities prerequisite, leaving only workflow context (quote -> checkout, auth) unstated, which is a minor gap for a creation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating the inner config keys and pointing to get_capabilities as the source of valid process/material/color ids, which is genuinely useful invocation guidance not present in the structured fields.

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

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

The description opens with a specific verb+resource ('Create a quote') and then outlines the payload shape. It does not name the sibling tools (update_quote, get_quote, discard_quote) it must be distinguished from, but the core purpose 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?

'See get_capabilities for valid ids' gives one concrete prerequisite for constructing a valid call, and 'Returns prices, speed options... and next_steps' hints at the quoting workflow. However, there is no guidance on when to create a new quote versus updating an existing one (update_quote) or when a quote must precede checkout, so usage is only implied.

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

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

Goes well beyond the annotations by spelling out the concrete consequences: the quote becomes 'expired', checkout links and USDC payment requests stop working, it can't be paid, and it can't be discarded once ordered or paid. This confirms and enriches the idempotentHint (repeat discard is harmless) and clarifies the destructiveHint=false nuance.

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

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

Three tight sentences, front-loaded with the purpose and effect, followed by idempotency and preconditions. No filler; every sentence carries a distinct fact an agent needs.

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

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

An output schema exists, so return values need not be explained, and the description still covers effect, irreversibility characteristics, and failure preconditions. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%; the single quote_id parameter is already documented as 'qt_... returned by create_quote'. The description adds no further parameter detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('close a quote') and immediately gives the business reason ('stops counting toward the open-quote limit'). The described state transition to 'expired' clearly separates it from siblings like update_quote and get_quote.

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

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

Gives a clear when-to-use condition ('a quote you no longer need') and explicit preconditions for failure ('an ordered quote, or one with a USDC payment received, can't be discarded'). It does not name a sibling alternative or direct the agent to update_quote for milder edits, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that it returns the authenticated account specifically (not an arbitrary account) and lists fields, but those fields are likely also in the output schema, so the added value is modest.

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, short fragment that front-loads the resource and its contents. Every word contributes, and there is no unnecessary verbosity.

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

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

Given the simplicity (no parameters), read-only annotations, and an existing output schema, the description is nearly complete. The only minor gap is the absence of an explicit verb, but the fragment 'The authenticated account: ...' is sufficient for an agent to understand the tool's purpose.

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, so the baseline is 4. The description does not need to explain parameter semantics, and it provides no misleading parameter information.

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

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

The description identifies the resource (the authenticated account) and enumerates the fields returned, so an agent can tell what it provides. However, it lacks an explicit action verb and does not differentiate from sibling tools such as get_capabilities or get_order, so it falls short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives are provided. The description only states what the tool returns, leaving an agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds a content list but no behavioral context such as caching, authentication requirements, or how the data is sourced, so it adds little beyond structured fields.

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 concise fragment, front-loaded with the capability categories. Every word contributes to defining the scope, with no wasted text. It is a list rather than a sentence, but that is appropriate for a zero-parameter getter.

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 rich annotations, the description only needs to cover purpose and usage. It covers purpose via the category list but omits any usage guidance or differentiation. For a simple zero-parameter tool, this is minimally viable, but the missing when-to-use context is a clear gap.

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

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

The tool takes zero parameters, so the baseline is 4 per the rules. The description does not need to explain parameter semantics, and none are present to document.

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 enumerates the specific capability categories returned (processes, materials, colors, finishes, services, speeds, file formats, limits, payment methods), making the resource scope very clear. It lacks an action verb (relying on the tool name) and does not differentiate from siblings, but no sibling overlaps in purpose.

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

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

No when-to-use guidance is provided, no alternatives mentioned, and no prerequisites stated. The description only lists content, leaving the agent to infer when this tool should be called.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond the field list — no error behavior for unknown order ids, no permission or rate-limit notes — so it contributes little on this dimension.

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

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

It is a single terse fragment with no filler, and the most useful content leads. But it is a verbless noun phrase rather than a structured statement, which reads as under-specification rather than disciplined brevity.

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

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

An output schema exists, so the returned fields (status, dates, tracking) did not need restating here, and annotations cover the safety profile. The genuine gaps — how it differs from list_orders/get_quote and behavior on a missing order — are minor for such a simple one-parameter read tool.

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

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

There is a single parameter with 100% schema description coverage, and the schema description is richer than the tool description, naming the ord_... prefix and the sources (list_orders, paid quote). Baseline 3 applies since the schema does all the work.

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

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

The fragment names the resource (order) and enumerates the data it surfaces (status, ship-by/arrive-by dates, tracking), so an agent can infer this is a single-order lookup. However, it supplies no verb and gives no signal distinguishing it from list_orders or get_quote, so the purpose is only implied.

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 says nothing about when to call this tool versus list_orders (bulk) or get_quote (pre-purchase). The only routing hint, 'from list_orders or the paid quote', lives in the input schema, not 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 declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: the fact that a part's analysis can be 'pending' and that the call can optionally block server-side for 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 sentences, no filler; the return contents are front-loaded and the optional wait behavior follows. Slightly dense enumeration in sentence one, but every item 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?

Return values are already covered by an output schema, and both parameters are fully documented in the schema; the description still summarizes the payload and the pending/wait nuance. For a 2-parameter read tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns the bump by explaining why wait_seconds exists (to wait on a pending part 'instead of polling'), which the schema only describes mechanically as '0 answers at once'.

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

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

States a specific resource (part) and enumerates exactly what is returned: status, measured geometry in mm, suggested units, DFM warnings, and fitting processes. That is far more concrete than a generic 'get_part', though it never names a sibling to contrast against.

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

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

Gives a clear usage instruction for the pending-analysis case: pass wait_seconds to block in this call 'instead of polling'. It does not say when this tool should be skipped or which sibling to prefer, but the polling-vs-wait tradeoff is explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description does add genuinely useful context by revealing that the payload carries warnings and next_steps (i.e. actionable state), but says nothing about freshness/staleness, quote expiry, or auth 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 front-loaded fragment that lists the returned fields with zero filler. It is compact and earns its place, though it is a bare fragment rather than a structured sentence.

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

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

An output schema exists so return values need not be spelled out, one required parameter is fully documented in the schema, and annotations carry the safety profile. The remaining gap is the absence of usage routing versus list_quotes/update_quote, which is minor given the surrounding coverage.

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

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

Schema coverage is 100% and the sole parameter quote_id is documented in the schema, including its qt_ prefix and origin. The description adds no parameter detail, so the baseline of 3 for high-coverage schemas applies.

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

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

The description names the resource (a quote) and enumerates the specific content returned: pricing, speeds, shipping options, warnings and next_steps. An agent can tell it is a single-quote retrieval rather than a listing, but it never explicitly contrasts with siblings like list_quotes or get_order.

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, and no alternative named. The only routing signal ('quote_id returned by create_quote') lives in the schema, not the description, so the description itself leaves usage 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 only declare the non-read-only, non-idempotent, non-destructive profile; the description adds genuinely new context: the URL is one-time, requires no auth header, and the part is returned on upload. It does not state how long the URL stays valid or what happens if the PUT fails.

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 core action and the key operational detail (no auth header), with zero filler.

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

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

With an output schema present, return values need no explanation, and the description covers the auth exception. However, for a workflow tool that sits alongside upload_part, omitting how the two relate and how long the one-time URL lives leaves a meaningful gap for correct invocation sequencing.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema (including the allowed file extensions and the CUI/ITAR confirmation). The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource (get a one-time URL) and the intended mechanism (HTTP PUT directly, no auth header). It is clear what the tool produces, but it never distinguishes itself from the sibling upload_part, which an agent could easily confuse with this pre-upload step.

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?

'large file' implies a size-based usage condition versus presumably smaller uploads, but there is no explicit when-to-use/when-not or any pointer to upload_part as the alternative path. Usage must be inferred rather than read.

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, so safety is covered. The description adds context annotations do not carry: results are scoped to 'this account' and sorted newest-first, which tells the agent what to expect from the result set.

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, the default ordering is front-loaded, and the filter guidance follows immediately. No sentence is wasted.

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

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

With an output schema present, return formatting is covered, and annotations cover the safety profile. For a one-optional-param list tool this is nearly complete; the only omission is any mention of result limits or pagination behavior.

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

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

Schema coverage is 100% and already documents quote_id's format (qt_...), so the baseline is 3. The description goes beyond that by explaining the intent behind the filter (verifying a checkout link was paid), which is meaning the schema does not supply.

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

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

The description names the resource ('Orders for this account') and a default ordering ('newest first'), which is enough to distinguish it from the singular get_order sibling. It stops short of using an explicit listing verb, but the resource+scope pairing is clear.

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

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

It gives one concrete use case ('filter by quote_id to check whether a checkout link was paid'), which implies when to reach for the filter. It never states when not to use this tool or points to alternatives like get_order for a single order, leaving routing 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 this a safe, idempotent, non-destructive read, so the safety bar is met. The description goes beyond that by disclosing that results are not repriced and that total_before_tax is the last priced value — a meaningful behavioral quirk. It doesn't mention pagination or the default-status scoping, but the core behavioral disclosure is strong.

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 compact sentences with zero filler. The result shape is front-loaded, followed immediately by the pricing caveat and the usage trigger — 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 an output schema present, the description does not need to explain return values, and it covers usage and the pricing caveat well. One small gap: 'your quotes' reads as all quotes while the schema default is status='open', leaving the default scoping to the schema rather than stating it.

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

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

Schema description coverage is 100%, so both limit and status are fully documented in the schema including the enum meanings and defaults. The description only echoes 'newest first' and adds no syntax or semantics beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific resource ('your quotes') with ordering ('newest first') and enumerates the returned fields (id, number, status, item_count, expires_at, total_before_tax). It also distinguishes itself from get_quote, so an agent can tell the list tool apart from the single-fetch sibling without opening either schema.

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

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

Gives an explicit alternative ('use get_quote for current prices') and a concrete trigger for calling this tool ('to find quotes to discard when you hit the open-quote limit'). This directly ties the tool to the discard_quote workflow and to the sibling get_quote.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the mutation risk is covered, but the description adds real value: it reveals the multi-call state machine, that the first call is a free requirements fetch, and the 'credit_confirmation_required' status/token branch. It stops short of stating authorization or rate-limit behavior.

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

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

Purpose is front-loaded, then the flow is laid out in three short, sequential sentences with no filler. It is dense but every sentence maps to a concrete call branch.

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 multi-step payment tool with an output schema carrying return values, the description covers the branching paths an agent must follow (requirements fetch, signed payment, credit confirmation). Only the when-to-choose-this-over-alternatives dimension is thin.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including payment_signature and confirm_credit. The prose mostly restates the schema's two-step flow rather than adding format or edge-case detail, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource (pay in USDC via x402) and scopes it to agent accounts. 'Option B' implies a competing payment path but never names it, so sibling differentiation against create_checkout_link or a credit-only option is left implicit.

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

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

It gives explicit call conditions: omit payment_signature to fetch requirements (nothing charged), then call again with the signed value, or use confirm_credit when credit covers the total. It does not, however, say when to prefer this over the other payment routes available among the 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?

Goes beyond the annotations ('destructiveHint: false', 'idempotentHint: true') by disclosing that a human reviews the request, that production may already have started so cancellation is not guaranteed, and the specific retry quirk where re-asking within 24 hours only amends the reason without a second notification. It does not cover auth or permission requirements.

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

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

Three compact sentences, front-loaded with the action and its precondition, then the review/uncertainty caveat, then retry semantics and where to observe the result. 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 mutating request tool with an output schema present, the description supplies everything else an agent needs: the eligibility condition, that fulfillment is human-mediated and may fail, idempotency behavior on retry, and where to read the outcome. Nothing material is missing.

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

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

Schema coverage is 100% and both parameters (order_id, reason) are documented in the schema, including the ord_... format and that the reason is for the reviewer. The description adds no further parameter detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Ask the shop to cancel an order') and immediately scopes it with 'that hasn't shipped', which separates it from the read-side siblings get_order and list_orders. An agent knows this is a request/negotiation action, not an immediate destructive cancel.

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

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

Gives the operative condition ('hasn't shipped') and points to the outcome path (order.status_changed webhook, get_order). It also covers the repeat-call case explicitly, though it never states the inverse condition (what to do if the order has shipped) or names a distinct alternative tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety and repeatability profile is covered. The description adds genuine behavioral meaning by explaining where each refund route lands (paying wallet vs account credit), but says nothing about reversibility, timing relative to a refund event, or whether it is per-order or account-wide.

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 with the scope condition front-loaded and zero filler. It earns its place, though the value definitions duplicate what the enum descriptions already carry, so it is slightly redundant rather than maximally tight.

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

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

With an output schema present, return values need no explanation, and annotations plus full schema coverage carry the mechanics. What is still missing for a mutation tool is lifecycle context: whether the preference must be set before a refund is triggered and whether it can be overwritten later.

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

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

Schema description coverage is 100%, and the schema already documents both the enum meanings and the order_id format. The description's parentheticals restate the same enum semantics rather than adding format, constraints, or defaults, so it is a baseline 3.

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

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

The description names the specific setting (refund preference), its applicable scope (USDC orders), and enumerates the two behaviors. An agent can tell this apart from every sibling, none of which touch refunds. It stops short of a clean verb+resource phrasing like 'Sets the refund preference for an order', but the 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 qualifier 'For USDC orders' acts as an implicit precondition, telling the agent this tool is only relevant to USDC-paid orders. However, it gives no guidance on when to call it relative to the payment/refund lifecycle, whether it can be changed after being set, or what alternatives exist for non-USDC orders.

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

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

Adds context the annotations do not carry: omitted fields stay (partial/PATCH semantics), and a new email or callback_url triggers a notification to the previous account email. Combined with destructiveHint=true and idempotentHint=true, the agent knows changes overwrite supplied fields but leave the rest intact. It does not say which values are rejected or what authorization is required.

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 compact sentences, zero waste, with the field scope and 'omitted fields stay' semantics front-loaded before the notification side effect. Nothing is repeated unnecessarily.

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

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

An output schema exists, so return values need not be described, and the description covers partial-update semantics, the notification side effect, and account-type scope. It stops short of stating permission requirements or validation failures for a destructive, mutation-capable tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the US address shape and the 'empty string removes it' behavior for callback_url. The description only restates the field list, adding no syntax or constraint detail beyond the schema.

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

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

States a specific verb (Change) and resource (the agent account) and enumerates the exact mutable fields: name, organization, email, ship_to, callback_url. The trailing scope note 'Agent accounts only' separates it from create_agent_account and get_account without ambiguity.

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 'Agent accounts only' restriction tells the agent when the tool is applicable, but there is no guidance on when to prefer this over create_agent_account or get_account, and no stated prerequisites. Usage is implied rather than prescribed.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact — config is merged into the item's existing config rather than replaced — but says nothing about re-pricing, editability windows, or what remove_item_ids/add_items imply for the quote state.

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 changeable fields, which is good. However the second sentence duplicates the schema's update_items description almost verbatim, so it consumes space without adding information beyond the merge note.

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 9-parameter mutation tool with an output schema and full schema coverage, the description is serviceable but incomplete at the conceptual level: it never mentions that items can be added (add_items) or removed (remove_item_ids), or that po_number/contact_email are settable, so an agent scanning only the description may miss that this tool also handles item add/remove.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including the speed enum and the item shapes. The description largely restates schema content (speed values, ship_to, update_items shape) and adds only the merge-vs-replace nuance, landing at the baseline for a schema-complete tool.

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 verb 'Change' plus the enumerated mutable fields (speed, ship_to, shipping_option, items) makes it clear this edits an existing quote rather than creating one. It doesn't explicitly name the quote resource or distinguish itself from discard_quote/get_quote in prose, but the field list is specific enough to identify the operation.

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: nothing states that the quote must already exist, must still be editable, or that this is the path to modify an existing quote versus create_quote or discard_quote. The agent must infer the call context from the required quote_id 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 only declare mutation/idempotency/open-world traits; the description adds operational constraints the annotations cannot convey: the 4 MB MCP request ceiling, the ~3 MB practical base64 limit, the mandatory no_controlled_data compliance gate, and the asynchronous 'pending' → 'ready' lifecycle.

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

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

Four tight sentences, front-loaded with the action and accepted formats, then limits, then compliance, then return/polling behavior. No filler and no repetition of structured data.

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 details needn't be spelled out, yet the description still notes the 'pending' status and polling path. Together with limits, compliance gating, and the large-file alternative, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it ties filename to the base64 path, explains the base64 size ceiling, and states no_controlled_data must be true as a compliance assertion rather than just a flag.

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

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

Opens with a specific verb and resource ('Upload a CAD file') and enumerates the accepted formats (STL, 3MF, OBJ, STEP) plus the two input channels (https URL or base64). This clearly separates it from siblings like get_upload_url and get_part.

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

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

Explicitly routes the agent: base64 only works up to ~3 MB due to the 4 MB MCP request limit, so 'use a URL or get_upload_url for larger files'. It also names the follow-up action (poll get_part until 'ready', or use wait_seconds).

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