Aithon

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

With no annotations, the description carries the behavioral burden and does well: it discloses status meanings, evidence source, price visibility, FCC lower-bound caveats, and the fact that confirm triggers supplier confirmation requests. It still leaves out latency, permissions, and fuller response 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?

Three front-loaded sentences with little wasted wording; the status list, caveat, and confirm behavior are presented efficiently. 'Honest status' is slightly promotional but does not meaningfully obscure the message.

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 five-parameter availability check with no annotations or output schema, it covers the critical statuses, data limitations, and confirm behavior. It is still thin on full response shape and on how category, service_ids, and phone affect the check.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the US business-address scope and explains confirm as a binding-answer request, but it adds little beyond the schema and does not clarify category, service_ids, or phone usage.

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

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

States a specific verb ('Check') and resource ('which suppliers can likely serve a US business address'), plus the status vocabulary and data source. It does not explicitly differentiate itself from adjacent siblings such as quote.request, so it is clear but not fully sibling-routing.

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?

Explains an important in-tool usage pattern: FCC-only results are likely/unknown and confirm:true asks suppliers for a binding answer. It does not say when to use this instead of quote.request or other siblings, nor 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?

No annotations are supplied, so the description carries the full burden. It never states that this is a mutating/persisting operation, whether drafts expire, what happens if the same session_id is reused, or what authorization the 'scoped' qualifier implies; the session_id note merely restates the schema.

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

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

Two short sentences with the core action first and the prerequisite second; nothing is redundant. The phrase 'for a scoped, agent-orderable service' is somewhat vague filler that could be replaced with concrete 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 five-parameter creation tool with a nested object, no annotations, and no output schema, the description should explain draft lifecycle, relation to order.draft/checkout, and what a successful call yields. Neither the meaning of 'cart draft' nor the next step in the flow 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 100%, so the parameters are already well documented, including quantity clamping, variant_key defaults, and service_configuration's nested fields. The description adds essentially nothing beyond the schema except the phrase 'caller-managed', which the schema already conveys.

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 (create a cart draft) and adds that the target is a scoped, agent-orderable service. It does not distinguish this from sibling tools like order.draft or quote.request, so an agent cannot tell from the text alone which draft mechanism to pick.

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

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

It gives one prerequisite (caller-managed session_id), which is useful, but offers no when-to-use guidance against order.draft, quote.request, or availability.check, and no when-not-to-use conditions. Usage is only implied by the 'cart draft' framing.

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?

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. "Get" implies a read, but read-only status, auth/permission scope (the word "scoped" hints at a narrowing but is unexplained), error behavior for unknown IDs, and return shape are all 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?

A single four-word sentence with no filler and the resource front-loaded. It is efficient, though brevity here edges toward under-specification rather than crispness.

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 annotations and no output schema, the description should explain what the call returns and what "scoped" restricts. Instead it leaves the agent guessing about return contents and scope, which is a real gap for a lookup tool in a catalog family.

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% for the single parameter, and the schema already explains that service_id comes from catalog.search. The description adds no further meaning about the ID format or expected values, so baseline 3 applies.

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

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

The description pairs a generic verb ("Get") with a resource ("service details") qualified by "scoped", which is the only distinguishing signal. It does not clarify what "scoped" means or how the result differs from catalog.search or catalog.order_schema.get, so an agent cannot confidently separate this from those siblings.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives. The only routing hint in the whole definition lives in the schema ("Service ID from catalog.search"), not in 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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read operation, but the description does not confirm read-only behavior, describe permissions, or explain the returned schema's shape or caching behavior.

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

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

The description is a single front-loaded sentence with no filler. The term 'machine-orderable' is somewhat jargon-heavy, but the structure is efficient.

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

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

The tool retrieves a schema, but there is no output schema and the description does not explain what the returned schema contains or how it relates to order.draft. For a schema-retrieval tool, this leaves out essential 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 100% and the parameter is already documented as 'Service ID from catalog.search'. The description adds only the phrase 'scoped service' and does not provide meaning beyond the input 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 has a specific verb ('Get') and resource ('machine-orderable schema'), but 'machine-orderable schema' and 'scoped service' are ambiguous. It does not clearly distinguish this tool from siblings like catalog.get, catalog.search, or order.draft.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The schema parameter notes that service_id comes from catalog.search, but the description itself provides no when-to-use or exclusion guidance.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses essentially nothing: not that this is a read-only operation, not pagination behavior beyond the schema's limit field, not result ordering, and not what a result item contains. Only the word "search" hints at non-mutating 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?

Three words with zero filler and the operation front-loaded. It is efficient rather than padded, though the brevity crosses into under-specification rather than crispness.

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 search tool with three optional parameters, no annotations, no output schema, and ten sibling tools in the namespace, the description should at minimum explain the scope and how results are returned. The schema covers inputs well, but the agent is left to infer what "scoped" means and what a call returns.

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

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

Schema description coverage is 100% — limit, query, and category each have clear descriptions including defaults, max values, and matching semantics. The description adds no parameter meaning of its own, 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?

"Search scoped catalog" names a verb (search) and a resource (catalog), so the basic operation is inferable. However, "scoped" is never explained — what the scope is (merchant? workspace? tenant?) is left to guesswork, and nothing distinguishes this from sibling catalog.get.

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 given. A sibling catalog.get exists that plausibly retrieves a single known item, but the description never states that search is for discovery versus get for retrieval by identifier, nor does it mention any prerequisites 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?

With no annotations, the description carries the full behavioral burden. "List" implies a non-mutating read scoped to the caller's owner, which is useful, but it says nothing about what happens when no mandates exist, whether results are paginated or identity-scoped, or whether mandates are enforced elsewhere in the toolset.

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 verb and resource, then a tight colon list of what comes back. Every clause carries information and nothing is repeated from structured fields.

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

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

There is no output schema, so the description must describe return values, and it names four of them: permitted actions, categories, monthly commitment ceiling, and expiry. Missing are mandate identity, per-mandate scoping, and empty-result behavior, but for a zero-parameter read tool this is largely adequate.

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 nothing for the description to disambiguate; the baseline applies. The parenthetical action names are arguably return-value semantics rather than parameter semantics, but they add no confusion.

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 ("List the mandates your owner has issued to you") and then enumerates the fields returned (actions, categories, monthly ceiling, expiry). That is far more specific than the bare name mandate.get, though it does not explicitly contrast itself with any sibling tool.

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

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

Usage is only implied: an agent can infer this is how you discover what you are permitted to do, but the description never says when to call it versus the action tools (quote.request, order.draft, availability.check) or that it should be consulted before attempting those actions. No when-not guidance either.

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 no annotations, the description carries the full burden, but it does disclose two non-obvious behaviors: the mandate signer is prompted to sign in, and no checkout URL is returned. It omits whether the draft persists, whether the call is idempotent, and what the response contains, leaving meaningful gaps for a mutation-style tool.

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

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

Three short sentences, each carrying distinct information: the action, the source constraint, the signing step, and the return-value caveat. Nothing is redundant and the key fact 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 tool with no annotations or output schema, the description covers the important surprises (sign-in prompt, absence of a checkout URL). It stops short of saying what a successful call returns, such as an order identifier, which an agent would still need to know.

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 0% and the single quote_id parameter has no description beyond format uuid. The description partially compensates by indicating the quote must be confirmed, adding a semantic constraint the schema lacks, but it doesn't clarify whether it must be the caller's own quote or how to obtain the ID.

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 ('Draft an order') and constrains the source ('from one of your confirmed quotes'), which distinguishes it from quote.request and cart.draft.create. It doesn't name a sibling explicitly, so it falls short of the top score.

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 'confirmed quotes' implies a prerequisite state for the quote, giving implicit when-to-use guidance. There is no explicit statement about when not to use it or which sibling (e.g. cart.draft.create) to pick instead, so guidance remains inferential.

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 no annotations supplied, the description carries the full disclosure burden. It does useful work by stating explicit exclusions ('Does not include the signer's email or a signing URL'), which prevents an agent from calling it expecting contact or link data, and 'Get' implies a read-only lookup. However, it says nothing about permissions, behavior when the order ID is unknown or belongs to another account, or rate limits.

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

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

Two sentences, front-loaded with the retrieval purpose and followed by the exclusions clause — an efficient structure with no filler. The field enumeration is dense and slightly overlapping ('envelope status and timestamps', 'signed time', 'timeline'), but each item still helps an agent judge whether the response contains the data it 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?

There is no output schema and no annotations, so the description must describe the return surface itself, which it does by listing the fields and naming the notable omissions. For a single-parameter read-by-ID tool that is largely sufficient; only error/not-found behavior and ownership/auth expectations are left uncovered.

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 single required parameter order_id has only a uuid format hint in the schema. The description adds a modest amount by framing the ID as identifying 'one of your orders', implying ownership scoping, but it gives no guidance on where the ID comes from or what happens with an invalid or foreign ID.

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 ('Get') and resource ('one of your orders') and then enumerates the returned content (status, amounts, envelope status, timestamps, signer name, timeline), so an agent knows exactly what this tool yields. It does not explicitly contrast itself with siblings like order.draft or quote.get, so sibling differentiation is left implicit through the 'your orders' scoping.

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. The phrase 'one of your orders' implies the caller must already have an order ID (i.e. retrieval, not creation), but the description never states that order.draft creates orders or that quote.get is for quotes, so the agent must infer routing from names 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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether cancellation is reversible, what state the quote moves to, whether it requires ownership or specific permissions, or what the response contains. Only the implied 'open' constraint is conveyed.

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 single sentence is front-loaded and free of filler. It is efficient, though its brevity leaves important behavior unstated.

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 no annotations, no output schema, and an undocumented required parameter, the description is too thin. It should at least clarify the effect of cancellation, ownership requirements, and possible failure states.

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 does not mention the quote_id parameter or its UUID format. It implies the identifier refers to an owned open quote but adds no detail on how to obtain or format it.

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 ('Cancel ... quotes'), so an agent immediately knows the operation. It is distinguishable from siblings like quote.get or quote.request, though it does not explicitly name them.

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

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

The phrase 'one of your open quotes' implies a precondition: the quote must belong to the caller and still be open. However, it does not explicitly say when to use this versus quote.get or quote.request, nor does it state what happens if the quote is already closed.

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 no annotations supplied, the description carries the full behavioral burden. It does useful work by disclosing the response shape (status, lines, totals, validity, order id) and signaling that order id is populated only after ordering, which is real lifecycle context. It stops short of stating that this is a non-mutating read, whether it requires ownership/authentication, or what happens for an invalid or expired 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 the action first and the returned fields as a compact list. Nothing is redundant and nothing needs to be moved forward.

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 getter with no output schema, the description usefully compensates by enumerating the fields returned. It is nearly complete; the remaining gaps are error and permission behavior, which matter less for a read-only lookup.

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

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

There is one parameter, quote_id, with 0% schema description coverage, so the schema gives only type and uuid format. The description's "one of your quotes" adds a meaningful constraint that the id must reference a quote owned by the caller, but it does not say where the id comes from or how it behaves if it names someone else's quote.

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 ("Get one of your quotes") and enumerates exactly what comes back: status, lines, totals, validity, and order id. This distinguishes it implicitly from quote.request and quote.cancel, though it never names those siblings to make the contrast explicit.

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

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

Usage is only implied: you fetch a quote you already have an id for. There is no statement of when to prefer this over quote.request or order.get, no prerequisite about obtaining a quote_id, and no guidance for the not-found or expired cases. The phrase "once ordered" hints at lifecycle positioning but doesn't spell it out.

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

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

No annotations are supplied, so the description must carry the behavioral burden. It discloses one important trait—reusing client_reference returns the same quote—but omits whether the call creates or mutates state, permission requirements, side effects, and error 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 with no filler, the core action stated first and the idempotency hint second. The text is appropriately sized and 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 9-parameter tool with nested objects, no annotations, and no output schema, the definition is too thin. It covers the core action and one parameter behavior but leaves tool selection, most parameter meanings, and mutation semantics undocumented.

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 11%, and the description explains just client_reference's reuse semantics. It adds no meaning for most of the 9 parameters, including address, quantity, term_months, variant_key, confirm_request_id, and service_configuration.

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

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

The description states the specific action (request a quote) and domain object (scoped service), distinguishing it from quote.get and quote.cancel by verb. However, it does not explicitly contrast itself with those siblings or clarify what 'scoped' means, so it falls short of full sibling differentiation.

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 relative to quote.get, quote.cancel, order.draft, or cart.draft.create. The only usage-like instruction concerns reusing client_reference for idempotency, which is a parameter behavior rather than a tool-selection rule.

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