SupplySlate

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

Annotations already convey non-read-only, non-destructive, non-idempotent. The description adds specific behavioral context by stating the action does not alter the 'immutable request package,' clarifying the non-destructive nature precisely. It also implies a side effect (sending a question to the buyer) consistent with readOnlyHint=false.

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 of 16 words, front-loaded with the action and including only essential qualifiers. No redundant or filler content.

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

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

For a simple 2-parameter tool with an output schema, the description is largely sufficient. It identifies the prerequisite ('approved supplier RFQ') and the non-mutating nature. However, it does not elaborate on the expected flow or response, but the output schema covers return values. Minor gaps remain in fully defining the match_id 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 description coverage is 0%, and the description does not explain match_id or question beyond their obvious names. It adds no detail about the match_id format (only the schema pattern) or the nature/content of the question, failing to compensate for the missing parameter descriptions.

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

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

The description clearly states the action (ask a clarification question), the target (buyer), and the subject (approved supplier RFQ), with the scope qualifier 'without changing the immutable request package.' This distinguishes it from mutation tools like revise_supplier_quote and decline_supplier_rfq.

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?

Provides clear context: it is used on an 'approved supplier RFQ' and explicitly says it does not change the package, implying it is for communication rather than modification. However, it does not explicitly name alternative tools or exclusion criteria, which would push it to 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 are all false and offer no positive safety info, so the description carries the burden. It reveals two key behaviors: it attaches a reference without copying bytes, and private/expiring URLs are the buyer's responsibility. However, it does not disclose side effects, permission requirements, reversibility, or whether the operation mutates the project revision beyond implicit context.

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 main action and key constraint, with no wasted words. The first sentence states what the tool does, and the second adds an important responsibility note. Exemplary conciseness.

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

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

The description is concise and covers the tool's core distinction, but given the complexity (8 parameters, 5 required, 3 enums, 0% schema coverage), it leaves gaps: no guidance on choosing artifact_type vs. purpose, no explanation of required fields, and no detail on how checksum or filename are used. The output schema exists, so return values are covered, but the description is not fully complete for a tool with this parameter count.

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 meaningfully explain the parameters. It lists general content types ('repository, document, drawing, datasheet, BOM, or design reference') that map loosely to artifact_type or purpose, but it does not clarify required parameters (project_id, source_url, data_classification) or optional ones like checksum_sha256 or media_type. The description adds minimal semantic value beyond what the enum values already convey.

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

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

The description clearly states the action: 'Attach an HTTPS repository, document, drawing, datasheet, BOM, or design reference to the current project revision without copying its bytes.' It uses a specific verb and resource, and the phrase 'without copying its bytes' explicitly differentiates it from the sibling tool create_artifact_upload.

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 on when to use this tool: for referencing external content via HTTPS rather than uploading bytes. The note 'Private or expiring URLs remain the buyer's responsibility until uploaded directly' implies an alternative action (upload), but no sibling tool is explicitly named, and formal when-not conditions are absent.

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: the URL is short-lived, one-time, private, and requires streaming the exact declared bytes with a SHA-256 checksum. These details go beyond the annotations, which are all false and offer no safety hints, adding meaningful context about constraints and expectations.

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 consists of two concise sentences: one stating the core purpose and one adding a critical usage constraint. Each sentence earns its place, and the description is front-loaded with the action, making it efficient and clear.

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 has 8 required parameters and an output schema, but the description lacks workflow context, parameter semantics, and guidance on how this fits into the artifact upload process. It covers the essential creation and the streaming requirement but leaves out explanations for the remaining parameters and the broader use case.

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

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

With 0% schema description coverage, the description is expected to explain the 8 parameters. It only clarifies that the declared size and SHA-256 checksum are used for stream verification, leaving project_id, media_type, artifact_type, purpose, and data_classification unexplained. This is insufficient for an agent to correctly populate all 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 clearly states the tool creates a short-lived, one-time private artifact upload URL, which is a specific action and resource. It distinguishes itself from sibling tools like attach_artifact_reference or create_catalog_import by focusing on the upload URL generation.

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 the tool is used when an artifact needs to be uploaded via a one-time URL, but it lacks explicit guidance on when to use it versus alternatives. No exclusions or alternative tool recommendations are provided, so the usage context 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?

The description indicates that the operation creates a durable import and mentions downstream effects like validation and mapping. It does not contradict the annotations (idempotentHint=true, destructiveHint=false). The description adds context about the workflow without repeating annotation details, which is appropriate given the annotations already cover idempotency.

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 concise, consisting of two sentences that pack substantial information without redundancy. It is well-structured, clearly stating the action and then the two primary usage modes.

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 complexity of the schema (nested objects, many fields) and the existence of an output schema, the description provides sufficient high-level context about the tool's purpose and workflow. It mentions validation and mapping, which gives the user a sense of what happens after creation. It does not need to explain return values since an output schema exists.

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

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

The description adds meaning to a few key parameters (rows and source_artifact_id) by explaining their roles in validation vs. mapping. However, it does not clarify other important parameters like source_type, idempotency_key, mapping, or source_url. With a schema coverage of 0%, the description only partially compensates for the lack of parameter explanations.

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 states the tool's primary function: creating a durable catalog import across various source types (CSV, XLSX, JSON, feed, API, document, manual). It distinguishes it from sibling tools by focusing specifically on catalog imports and mentioning the two modes of operation (parsed rows vs. artifact/source reference).

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 actionable guidance on how to use the tool: either supply parsed rows for immediate validation or provide an artifact/source reference to enter the mapping workflow. This gives clear conditions for usage, though it does not explicitly contrast with alternatives like upsert_supplier_catalog.

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

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

Annotations already cover idempotency and non-destructiveness, so the description only needs to add extra context. It adds 'durable' (persistence) and the authentication requirement ('requires a scoped buyer credential'), which are useful. However, it doesn't disclose other behavioral traits like validation rules or potential side effects beyond creation.

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 sentence with no redundant phrasing. It front-loads the core action and immediately follows with the credential constraint, earning every word.

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 tool's complexity (16 parameters, 5 required, nested requirements array, output schema), the description is drastically under-specified. It does not explain what a 'durable supply project' entails, what the brief should contain, or the meaning of demand_lane/project_type. The existence of an output schema reduces the need to document return values, but the input side remains insufficiently described for an agent to know how to construct a valid request.

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

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

With schema description coverage at only 6%, the description had a responsibility to explain key parameters, but it does not. The mention of origin types maps to the origin_type enum already present in the schema, adding no new semantic value. Required fields like name, project_type, demand_lane, and brief are completely unexplained, leaving agents to infer their meaning from names and types alone.

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?

Description states a clear action ('Create a durable supply project') and enumerates specific origin types (idea, file, BOM, exact part, RFQ), making the tool's purpose distinct from sibling tools like source_project or create_purchase_plan. The verb+resource combination is precise and actionable.

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 usage when a project needs to be created from a listed origin, and mentions a credential requirement, but does not explicitly contrast with alternatives or state when not to use this tool. It provides enough context for basic selection but lacks exclusions or comparisons to sibling tools.

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

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

The description adds significant behavioral detail beyond the annotations: it creates an 'unpaid provider order', 'never submits payment', and 'never exposes payment credentials to SupplySlate'. These are non-obvious safety guarantees that meaningfully extend the annotation data (readOnlyHint=false, destructiveHint=false).

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 focused sentences: the first sets the action and precondition, the second discloses a critical safety property. Every word earns its place, with no redundancy or 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 tool with six parameters and nested objects, the description covers the main mission, the approval precondition, and safety behavior. Since an output schema exists, it need not describe return structure, but it could have mentioned error conditions or validation of the purchase plan state, leaving a small 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?

Schema description coverage is only 50%; the schema documents contact, ship_to, and shipping_option_id, but purchase_plan_id, merchant_group_key, and return_url are left unexplained. The description provides no per-parameter details to bridge this gap, so the meaning of those three parameters remains unclear.

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 ('create'), a specific resource ('supplier-hosted payment link'), and a clear scope ('for a checkout-connected provider offer'). It also includes a crucial precondition ('After a human has approved the exact purchase plan'), which differentiates it from sibling tools like create_purchase_plan and get_checkout_handoffs.

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

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

The description gives a clear timing precondition ('after a human has approved the exact purchase plan') and indicates the intended use for checkout-connected provider offers. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks full contrastive 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?

Beyond the annotations, the description adds valuable behavioral context: the plan is immutable and the action only records a plan without approving or purchasing. This clarifies side effects and boundaries, with no contradiction to annotations.

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

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

Two sentences, front-loaded with the primary action, no fluff. Every word contributes to understanding the tool's purpose and constraints.

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 output schema, annotations, and schema patterns, the description is largely complete: it covers core intent, constraints, and side-effect boundaries. It lacks explicit guidance on idempotency key usage, but this is not essential for basic invocation.

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

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

Schema description coverage is 0%, and the description only indirectly explains quote_item_ids ('selected current quote lines'). The semantics of request_id, idempotency_key, and expires_at are not addressed, leaving the agent to infer from parameter names and patterns.

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

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

Description uses a specific verb ('Create') and resource ('purchase plan'), with clear scope ('from selected current quote lines', 'at most one commercial option per requested line'). It distinguishes this creation action from approval or purchasing actions.

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 states what the tool does not do ('neither approves nor purchases anything'), providing exclusion guidance. However, it does not explicitly name alternative tools like request_purchase_approval for those follow-up actions.

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 indicate a mutating operation (readOnlyHint false, idempotentHint false). The description adds that acceptance is the state-changing decision and restricts to unshipped orders, which is useful. However, it does not disclose consequences such as what happens to the order after acceptance/rejection, or any additional side effects beyond the annotation hints.

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

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

The description is two sentences, front-loaded with the main action, and every phrase adds value. It is concise without redundancy, effectively stating the scope and the key behavioral nuance (acceptance is state-changing).

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. However, the description omits parameter details for note and merchant_reference, and it does not specify post-decision effects (e.g., order cancellation flow). Given the tool's complexity (5 params) and openWorldHint=true, the description is incomplete.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It implicitly covers order_id, cancellation_request_id, and decision via the phrase 'buyer cancellation request' and 'Accept or reject,' but it does not address note or merchant_reference at all. With five parameters and no schema descriptions, the description fails to fully compensate.

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

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

The description clearly states the tool's function: accepting or rejecting a buyer cancellation request for a supplier's unshipped merchant order. It uses a specific verb ('Accept or reject') and a specific resource ('buyer cancellation request for the authenticated supplier's unshipped merchant order'), which distinguishes it from siblings like request_order_cancellation and update_supplier_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?

The description provides clear context: it is for a supplier responding to a buyer cancellation request on an unshipped merchant order. This implies when to use it, though it does not explicitly name alternatives or exclusions. The context is specific enough to differentiate from related tools, but there is no explicit 'when not to use' 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 this is a non-read-only, non-idempotent, non-destructive operation. The description adds useful context about the 'approved' state prerequisite and the routing outcome, but it does not disclose side effects such as finality, notifications, or whether a decline can be undone.

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 well-structured sentence that front-loads the action and object. Every word adds value, and there is no redundant repetition of schema or annotation 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?

Despite having an output schema and annotations, the description is too thin for a tool with three required parameters and zero schema descriptions. It fails to explain the match_id identifier, the reason_code choices, or the required format of the reason, leaving the agent without enough guidance 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?

Schema description coverage is 0%, so the description must compensate for explaining the three required parameters. It only mentions a 'structured reason,' which hints at reason_code and reason, but it does not explain match_id, the meaning of the reason_code enum values, or the expected content of the reason text.

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 ('Decline') with a clear resource ('an approved RFQ') and a qualifier ('with a structured reason'). This clearly distinguishes it from sibling tools like submit_supplier_quote, revise_supplier_quote, and ask_rfq_clarification.

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: this tool is for declining an approved RFQ, and the stated purpose ('so the buyer and network can route more accurately') implies when it should be used. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds a boundary by noting it explains 'what it does not do', reinforcing the informational nature. Since this is a pure explanation tool, no further safety disclosure is needed.

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 conveys the complete purpose, boundaries, and usage context with no waste. Every phrase adds value.

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 tool's simple meta-descriptive nature, empty schema, and existing output schema/annotations, the description is fully sufficient. It answers what, what-not, and when-to-use completely.

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 has zero parameters, so the baseline is 4. The description does not fabricate parameter details and correctly focuses on the tool's purpose.

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 the specific verb 'Explain' with the resource 'SupplySlate' and clearly delineates the scope: what it does, what it does not do, and usage timing. This distinguishes it from sibling tools that perform direct actions on data.

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

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

It explicitly states the context for use ('when a buyer-owned agent should use it'), which gives clear guidance. However, it does not mention exclusions or alternative tools, so it falls short of a perfect score.

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, setting a clear safety baseline. The description adds valuable behavioral context by specifying the output granularity: it returns hierarchy, quantities, sourcing state, and interface dependencies, which would not be known otherwise. It also notes 'current revision,' distinguishing from version history or draft access, which enriches the interaction model.

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, precisely worded sentence that packs in the tool's purpose, scope, and return contents without any wasted words. Every phrase adds information. This is a model of efficient communication.

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 low-complexity read tool with an output schema, the description is sufficiently complete: it tells the agent what the tool does and outlines the semantic groups in the output (hierarchy, quantities, sourcing state, dependencies). The presence of an output schema obviates the need to detail return values. The only minor gap is not indicating pagination or large response handling, but that is beyond the scope of a typical description.

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

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

With 0% schema description coverage, the description must clarify the two parameters. It only says 'one project BOM,' which suggests bom_id but leaves project_id's role ambiguous and fails to explain the relationship between the two (e.g., project_id scopes the BOM). The description does not compensate for the lack of parameter details 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 'Read' and a clear resource, 'the current revision of one project BOM,' and enriches it with the kind of data returned (hierarchy, quantities, sourcing state, interface dependencies). It clearly differentiates from sibling read tools like get_project or get_requirement_schema by focusing on BOM revision retrieval. This is a model example of a clear, specific, and distinct 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?

The description implies usage for reading a single BOM but does not provide explicit guidance on when to choose this tool over alternatives like get_project or get_purchase_plan. There is no mention of exclusions, prerequisites, or typical use cases beyond the obvious read action. The intended use is understandable but relies on inference rather than explicit direction.

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, so the safety profile is covered. The description adds useful context about the business model: suppliers remain merchant of record and SupplySlate does not process funds. This goes beyond the annotations without contradicting them.

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 concise sentences. The first sentence immediately states the action and scope, and the second provides important business context. There is no filler or redundancy.

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

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

With one parameter, an output schema, and annotations covering read-only/idempotent behavior, the description adds sufficient business context (handoff types, merchant of record, no funds processing). It is complete for a list operation.

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

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

Schema description coverage is 0% and the description does not explicitly explain the purchase_plan_id parameter. However, the singular parameter is self-explanatory by name, and the phrase 'for an approved plan' hints at the requirement. This is adequate but not fully compensatory for the lack of schema documentation.

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 explicitly names the verb 'List' and identifies the resource as 'merchant-hosted checkout, supplier invoice, or merchant-order handoffs' scoped to 'an approved plan.' This clearly distinguishes it from sibling tools like create_provider_checkout_handoff (create vs. list) and get_order (single order vs. list of handoffs).

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 usage when you need to view handoffs for an approved plan, establishing a clear context. It does not explicitly mention when not to use it or name alternatives, but the 'approved plan' prerequisite provides meaningful 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false already present, the description adds some context beyond annotations — namely the 'published' qualifier (implying unpublished versions may not be readable) and the exact-match semantics on subject/object. It doesn't address error semantics or what happens for missing/updated values, but it's consistent and modestly additive. 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?

One sentence, ~22 words, front-loaded with the verb 'Read,' and every phrase earns its place — 'published,' 'exact,' and the field enumeration all convey meaning. No fluff or repetition of the tool name.

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

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

For a single-ID read-only getter with a rich output schema and full annotation coverage, this is nearly complete. The only gap is the unp Explored 'published' semantics — how unpublished assertions are handled — but given the low complexity, the description is adequately scoped.

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

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

Schema description coverage is 0% and the description never mentions compatibility_id. The parameter name is self-explanatory and the single-ID lookup pattern lowers the cost of omission, but by the rubric the description must compensate when coverage is low, and it does not. A short gloss on the ID's provenance or format would have helped.

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?

Uses a specific verb ('Read') plus a clear resource ('one published compatibility or substitution assertion') and a precise scope ('exact subject, object, conditions, confidence, evidence source, and observation time'). Clear and specific, though it doesn't explicitly differentiate itself from the sibling get_* tools — though no sibling overlaps with 'compatibility' domain, so the omission is minor.

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

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

No guidance on when to use this tool versus an alternative. There's no mention of when not to use it, no alternative tool names, and no conditions under which a different read path (e.g., search or list) would be preferable. Implied usage only via 'one' and 'published.'

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

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

Annotations already establish read-only and idempotent behavior. The description adds that the tool provides connection details for MCP and REST, but it does not disclose additional behavioral traits such as return structure, authentication requirements, or rate limits. It neither contradicts annotations nor enriches them substantially.

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 concise sentence that front-loads the purpose and audience. No fluff, every word contributes to understanding what the tool does.

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

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

The tool is simple with one optional parameter and an output schema. The description adequately states what is returned (connection details) and the audience. It could mention that the output varies by client, but output schema likely covers that. For this level of complexity, the description is complete enough.

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

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

Schema coverage is 100% and the single 'client' parameter has a clear description and enum. The tool description adds no additional meaning beyond the schema, which already fully explains parameter semantics. Baseline 3 applies because the schema does the heavy lifting.

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 states the tool returns exact connection details for MCP and REST specifically for SupplySlate. It uses a specific verb ('Return') and resource ('connection details'), and the audience scope (buyer, developer, agent operator) distinguishes it from sibling tools like describe_supplyslate.

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 usage when connection details are needed (when a buyer, developer, or agent operator needs to connect to SupplySlate). It provides clear context but does not explicitly mention alternatives or when not to use this tool. Sibling tools are not referenced, but the intended scenario is clear.

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. The description adds behavioral nuance by emphasizing the discovery-only nature and stating what actions it does not perform, which goes beyond the annotations and provides valuable context.

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 consists of two concise sentences, with the first sentence clearly stating the purpose and the second adding an important boundary. Every word earns its place, and the 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?

The tool is simple (no parameters) and has an output schema, so the description does not need to explain return values. The description fully covers the tool's purpose and non-actions, and the annotations cover safety traits, making the description complete for effective use.

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 has zero parameters, and the schema description coverage is 100%. Per the rubric, a baseline of 4 is appropriate when there are no parameters, as the description does not need to compensate for any parameter documentation gaps.

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

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

The description clearly states the tool's function with a specific verb ('Read') and resource ('attributed live fabrication capabilities from the connected AFN provider'). It also distinguishes this tool from action-oriented siblings by noting it is 'discovery only' and does not upload designs or request 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 provides clear context for when to use this tool (when you need to read capabilities without performing other actions) and explicitly states exclusions ('neither uploads a design nor requests a quote'). However, it does not explicitly name alternative tools, 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=true, idempotentHint=true, and destructiveHint=false. The description adds the 'merchant-confirmed' scoping and the list of returned data, providing useful behavioral context beyond the annotations. 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?

The description is a single, well-structured sentence that front-loads the verb and object and then compactly lists the included data. No unnecessary words 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 simple one-parameter read operation with an output schema, the description is complete. It states the scope (merchant-confirmed) and the content fields, and the annotations cover safety and idempotency. No critical behavioral details are missing.

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

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

Schema has order_id with a pattern but 0% description coverage. The description names the resource but does not explicitly explain how to construct or format order_id, though the name and pattern make it fairly self-evident. It adds the 'merchant-confirmed' qualifier but little else.

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 states the verb 'Read' and the resource 'one merchant-confirmed order', and enumerates the specific data included (items, fulfillment, shipments, issues, evidence, event history). This distinguishes it from list_orders by indicating a single order with full detail.

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 usage for a single order via the required order_id, but does not explicitly mention alternatives such as list_orders or list_supplier_orders, nor state exclusions. It gives no direct guidance on when to choose this over a list 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: true and destructiveHint: false. The description adds useful behavioral scope by stating only published canonical products are returned and by listing the kinds of information included, such as variants, evidence scope, observation dates, and freshness.

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 entire description is one tightly scoped sentence. It avoids repetition of annotations, does not restate the input schema, and uses front-loaded structure: verb, resource, and then the included payload features.

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 return value details do not need to be repeated in the description. The remaining gap is product_id usage guidance, but for such a simple one-parameter getter, the description is otherwise behaviorally complete enough.

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

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

The schema has only one parameter, product_id, with 0% schema description coverage. The description never clarifies where product_id comes from, what it represents beyond an identifier, or how it relates to search results. The parameter name itself is self-explanatory, but the description does not compensate for the missing parameter documentation.

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 precise verb and resource: "Read one published canonical product". It clearly distinguishes this from listing/search tools by emphasizing "one" and "published canonical", so it reads as a singular fetch-by-ID tool rather than a search or aggregate endpoint.

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 conveys that this tool is for retrieving a single published canonical product, with no ambiguity about the intended use. It does not explicitly name alternatives or exclusion cases, but the contrast with search_products and list_* tools is obvious enough from the wording.

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 the safe-read nature is covered. The description adds context about the 'current immutable-capable revision' and 'validation history', which are behavioral details beyond the annotations. However, it does not disclose behavior around errors, permissions, or rate limits, leaving some transparency gaps.

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 that lists all returned components without wasted words. It is concise and well-structured, earning full marks.

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 presence of an output schema, robust annotations, and only one parameter, the description provides adequate context for a safe read operation. It clearly enumerates the scope of returned data. It doesn't mention prerequisites or edge cases, but the annotations and simple parameter make this acceptable. The description is complete enough for a straightforward getter.

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 project_id at all. The parameter's meaning is only implicit from the tool name and the pattern in the schema. Since the description fails to compensate for the lack of schema documentation, the parameter semantics receive a low score despite the parameter being self-descriptive.

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 states the verb 'Read' and the resource 'project', enumerating the specific subcomponents (immutable-capable revision, requirements, artifacts, BOM summaries, validation history) that distinguish it from siblings like get_bom or list_project_validations. This is a precise, resource-specific statement of 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?

The description implies when to use the tool: when you need a comprehensive project read including multiple related entities. However, it provides no explicit guidance on alternatives or exclusions, such as noting that get_bom provides full BOM details or list_project_validations provides validation history. The usage context is clear but not explicitly contrasted with sibling tools.

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

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

The description aligns with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds context on the response contents. However, it does not disclose additional behavioral traits such as versioning semantics, error handling, or side effects beyond what annotations already provide.

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

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

The description is a single sentence, front-loaded with the primary action ('Read') and resource, followed by a concise list of included data elements. Every part adds value 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?

The description provides a high-level summary of the tool's function and its return contents, which is sufficient given the presence of an output schema and annotations. It lacks explicit usage context or fallback behaviors, but these are likely covered by the schema and annotations for a simple single-parameter getter.

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 explicitly document the purchase_plan_id parameter. The phrase 'one exact purchase-plan version' indirectly relates to the parameter, but the description fails to compensate for the low coverage by explaining how to specify the ID or any constraints.

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 states the specific verb 'Read' and the resource 'purchase-plan version', and lists the included components (lines, merchants, totals, etc.). This distinguishes it from sibling tools like create_purchase_plan and other getters by focusing on reading a specific version.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it or any prerequisites. The phrase 'exact version' implies a use case, but it is not stated explicitly.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate the safe read-only nature. The description adds context by enumerating what the schema contains (required fields, recommended fields, accepted artifacts, safety notes). However, it stops short of disclosing deeper behavioral traits like authentication needs, rate limiting, or error behavior, and 'evidence-safe' itself is never explained. 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 sentence that front-loads the verb and resource before enumerating contents—efficient and well-structured. The only flaw is the modifier 'evidence-safe,' which is stylistically extraneous yet unexplained, slightly muddying an otherwise crisp description.

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 strong supporting context—comprehensive readOnly/idempotent annotations, 100% parameter documentation, and a declared output schema—the description is largely sufficient. The tool's contract is well-covered by the combination of fields. The primary gap remains the undefined 'evidence-safe' terminology and the absence of a pointer to sibling tools for related lookups, but overall the description is complete for this tool's simple read-only contract.

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%, as the schema thoroughly documents both parameters: identifier is described as 'Category code, fabrication-process slug, or fabrication-process ID' with min/max length, and type explains it is for 'disambiguation when an identifier could exist in both namespaces.' The description's mention of 'configurable supply category or fabrication process' parallels the schema's enum but adds no new parameter-level meaning, 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?

The description uses a specific verb ('Read') and a specific resource ('the evidence-safe input schema for a configurable supply category or fabrication process'), which clearly distinguishes this getter from sibling tools like get_bom or get_project. It also previews the schema contents (required fields, recommended fields, accepted artifacts, safety notes). The term 'evidence-safe' is a genuine ambiguity—unexplained jargon—that prevents a perfect 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?

No usage guidance is provided relative to alternatives such as get_connection_guide, get_compatibility, or get_sourcing_request. There is no 'use this when,' no 'for X use Y instead,' and no mention of prerequisites or exclusions. The only implicit hint is in the 'type' parameter's disambiguation note, which is parameter-level context rather than tool-level 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?

The description adds the access-control nuance of 'authenticated buyer' and specifies the data returned (status, line items), which is not in the annotations. The annotations already declare readOnlyHint and idempotentHint, so the description complements them with useful scoping context.

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, focused sentence of 12 words that leads with the action verb and identifies the resource and data scope. There is no repetition, filler, or unnecessary detail.

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 getter with one parameter, a clear safety profile from annotations, and an output schema, the description provides all necessary invocation context: the resource, its scope, and what is returned. It is complete without needing to explain return values or error cases.

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 only parameter request_id is given a regex in the schema, but no description. The tool description implies that this ID identifies a buyer sourcing request, adding some meaning beyond the raw schema. However, with 0% schema description coverage, more explicit parameter explanation would be expected.

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 states the tool reads the current status and normalized line items for one authenticated buyer sourcing request. The verb 'Read' and the specific resource 'one authenticated buyer sourcing request' make the purpose unambiguous and distinguish it from siblings like list_sourcing_requests.

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 that this tool is for retrieving a single, specific sourcing request belonging to the authenticated buyer, which implicitly tells you not to use it for listing or other entity types. However, it does not explicitly reference alternatives or provide when-not-to-use guidance, preventing 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. The description adds a 'public' qualifier and indicates the response includes evidence and source URLs, which is useful context. It does not cover error cases, but for a simple read operation with strong annotations, this is adequate.

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 conveys the essential action and key additional context. No wasted words, and the structure is immediately scannable.

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 tool's low complexity, one required parameter, and the presence of an output schema, the description covers the core behavior adequately. It explains the content of the return (evidence, source URLs), and annotations cover safety. Missing guidance on alternatives is a minor gap, but not critical for this simple read tool.

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

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

Schema description coverage is 0%, and the description does not compensate by explaining the supplier_id parameter beyond the obvious 'profile' context. It relies on the parameter name and schema pattern, but does not add semantic detail such as where to obtain the ID or any constraints beyond the pattern.

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 states the verb 'Read' and the resource 'one public supplier profile', and adds distinctive detail about source URLs and evidence for categories, capabilities, and brand claims. This differentiates it from search_suppliers and get_supplier_offers, though not explicitly from the near-sibling get_supplier_profile.

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 explicit guidance on when to use this tool versus alternatives. It implies a read operation for a single supplier, but it does not mention when to prefer it over get_supplier_profile or search_suppliers, nor any exclusions or prerequisites.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive operation, so the bar is lower. The description adds meaningful behavioral context beyond annotations: it states that SupplySlate returns explicit tradeoffs and applies no hidden winner score. It also clarifies that data is normalized and includes unquoted lines, giving insight into output quality and methodology. This adds value without contradicting annotations.

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

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

The description consists of two focused sentences, front-loaded with the action verb and resource. The first sentence efficiently lists the key data points, and the second sentence adds a unique, useful behavioral note about tradeoffs and no hidden winner score. There is no redundancy or 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 and annotations indicating a safe read operation, the description thoroughly covers purpose, scope, and data content. It lacks only explicit details such as pagination or error handling, but these are not essential given the output schema and simple parameter. The tool's function is well contextualized.

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

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

The schema has one parameter, request_id, with a pattern but no description (0% coverage). The description's phrase 'for one buyer sourcing request' implicitly maps request_id to the sourcing request, but it does not explicitly describe the parameter format or provide examples. The parameter is simple and self-explanatory, so the description provides adequate but minimal compensation for the lack of 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 clearly uses the verb 'Retrieve' with a specific resource: 'current normalized supplier quote revisions for one buyer sourcing request.' It lists the included data (unquoted lines, compatibility, price, availability, lead time, terms, evidence) and differentiates from siblings by scoping to one sourcing request and emphasizing normalization. This makes the tool's purpose unambiguous and distinct.

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 usage when needing a consolidated, normalized view of all supplier quotes for a single sourcing request, but it does not explicitly state when to use it over alternatives like get_supplier_rfq or list_supplier_rfqs. There is no exclusion or named alternative, so the usage context is present but not fully 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?

The read-only, idempotent, and non-destructive behavior is already reflected in annotations, and the description adds useful context about required authentication and the inclusion of a catalog-item count. There is no annotation contradiction or hidden side effect.

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

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

The description is two short sentences with no filler: the first states the read behavior, the second states the auth requirement. It is front-loaded and every sentence contributes meaning.

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 zero parameters, a rich annotation set, and an output schema already present, the description fills the remaining context gap by noting the authenticated nature of the request and the exact data being read. Nothing essential 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?

There are zero parameters and the schema coverage is naturally complete. The description adds value by explaining that the supplier identity comes from the API key rather than from a parameter, which is the only parameter-related ambiguity that could exist.

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 states the verb 'Read' and names the resources: the authenticated supplier's SupplySlate profile and the current catalog-item count. It also differentiates itself from the sibling get_supplier by emphasizing 'authenticated supplier' rather than a general supplier lookup.

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

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

The description gives one relevant prerequisite ('Requires a supplier API key') and implies the intended context of an authenticated supplier session. However, it does not explicitly state when to prefer this tool over siblings like get_supplier or get_supplier_offers, so selection guidance is mostly inferred.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the authentication requirement (supplier API key) and the restriction to approved RFQs, plus the note about normalized buyer line items. These are useful behavioral details beyond the annotations, and there is 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?

The description is two short sentences, front-loaded with the core action and then the key prerequisite. Every word contributes value, with no redundancy or 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?

Given the simple nature (one parameter, no nested objects), the presence of an output schema, and strong annotations covering safety, the description is adequate. It covers the purpose, scope (approved RFQ), and authentication requirement. It omits error handling or pagination, but for a simple read operation, this is sufficient.

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

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

The schema only provides the parameter name (match_id) and pattern, with no description (0% coverage). The description adds meaning by implying that match_id identifies an approved RFQ, and the requirement for a supplier API key introduces an additional constraint not present in the schema. This is adequate for a single-parameter 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 description clearly states the action ('Read') and the resource ('an approved RFQ and its normalized buyer line items'), which is specific and distinguishes it from sibling tools like list_supplier_rfqs (which lists multiple RFQs) and decline_supplier_rfq (which modifies an RFQ).

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 usage: it should be used when a specific RFQ (identified by match_id) needs to be read, and it requires a supplier API key. It does not explicitly contrast with list_supplier_rfqs, but the context is clear enough. No explicit exclusions are given, but the scope to 'approved' RFQs provides a conditional.

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, covering the safety profile. The description adds context that the listing includes artifacts and requirement schemas, but does not disclose other behaviors such as pagination or whether all processes are returned.

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

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

A single, front-loaded sentence with no waste. It starts with the verb 'List' and packs all necessary information into 16 words.

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 zero-parameter, read-only list tool with annotations and a stated output (artifacts and requirement schemas), the description is largely complete. It could be slightly more explicit about return format or whether filters exist, but with such a simple tool this is sufficient.

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

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

The schema has 0 parameters, so the baseline is 4. The description does not need to explain parameters, and it does not add any parameter-related meaning beyond the schema's empty object.

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 states a specific action (list) and resource (configurable fabrication, kitting, assembly, and test processes), and specifies the output (required artifacts and requirement schemas). It distinguishes itself from sibling tools like get_live_fabrication_capabilities by focusing on configurable processes rather than live capabilities.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or contexts, leaving the agent to infer suitability from the resource name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable semantic context by clarifying that plans and queued handoffs are never included, which is not directly inferable from the annotations. This helps the agent understand exactly what the result set contains.

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 concise sentences. The first states the core purpose, and the second adds a crucial exclusion criterion. There is no redundant wording 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?

For a parameterless list tool with an output schema and comprehensive annotations, the description fully scopes the result set and clarifies a common point of confusion (what counts as an order). No additional information is needed to use 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 has zero parameters and is fully described (100% coverage). With no parameters, the description need not explain parameter syntax or purpose; the baseline of 4 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 uses a specific verb ('list') and clearly identifies the resource ('merchant-confirmed orders for the buyer organization'). It also distinguishes the result set by explicitly excluding plans and queued handoffs, which helps separate it from other order-related tools like list_supplier_orders.

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: it is scoped to the buyer organization and only includes merchant-confirmed orders. It also states what is not represented (plans/queued handoffs), giving implicit guidance on when to use this tool, though it does not explicitly name alternatives such as get_order or list_supplier_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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context beyond them: it mentions the reports are versioned and emphasizes that listing them does not imply engineering approval. This gives the agent a clearer behavioral picture of what the tool does and does not do.

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 that directly states the purpose and the key caveat. Every word earns its place; there is no fluff or redundancy.

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

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

For a simple list tool with one parameter, strong annotations, and an output schema, the description covers the essential context: what is listed (versioned validation reports) and what it does NOT imply (engineering approval). It is complete enough without needing to explain return formats or pagination.

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

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

The schema has 0% description coverage, so the description must compensate, but it only says 'for a project' without explaining the project_id format or any additional semantics. The pattern in the schema is the only real guidance, so the description adds minimal parameter value beyond the schema.

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

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

The description clearly states the action (list), resource (versioned validation reports), and scope (for a project). It also adds a distinguishing caveat about not implying licensed engineering approval, which separates it from validation/approval-related tools like validate_project.

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

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

The description gives clear context that this tool provides validation reports without conferring approval, implicitly telling the agent it is for informational viewing, not for sign-off. This is a useful exclusion, though it does not name alternative tools explicitly.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context: these categories are 'editable' and the list is not a hard boundary for requests (the outside-list caveat). This goes beyond the annotations and helps the agent understand the tool's role in the broader sourcing flow. No contradiction with annotations was found.

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 concise sentences. The first sentence is front-loaded with the action and target. The second sentence delivers a crucial caveat without waste. Every word contributes to usability.

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 tool's simplicity (no params, output schema present), the description fully covers what the agent needs: the list’s scope, the current acceptance status, and the important caveat that requests can extend beyond the list. It is complete for an agent to select and invoke 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, so the schema provides no information. The baseline for no params is 4, and the description adds no parameter-specific details because none are needed. It appropriately focuses on output semantics instead.

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 'List' with a clear resource 'editable supply categories' and adds a scope qualifier 'currently accepting requests'. This distinguishes it from sibling tools like list_supplier_taxonomy and list_sourcing_requests. The additional note about submitting outside the list further clarifies its 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?

The description implies when this tool is relevant: when the agent needs to know which supply categories are currently open for requests. It provides a key exclusion by stating that agents may still submit a precise request outside this list, which prevents over-reliance on the list. However, it does not explicitly name alternative tools or scenarios to avoid.

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 known. The description adds behavioral context by specifying that results are limited to the authenticated buyer organization and aggregated across API keys and OAuth agents. 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?

The description is a single, economically worded sentence that front-loads the action and resource. Each phrase adds information—scope, ownership, and aggregation.

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 list operation with a read-only annotation and output schema, the description is reasonably complete. It states the returned scope and the cross-agent behavior. However, it omits any detail about the 'limit' parameter and does not define 'recent', so it falls short of a perfect score.

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 contains a single 'limit' parameter with default 20, min 1, max 50, but lacks a description (coverage 0%). The tool description does not mention 'limit' or explain its meaning, leaving the agent to infer from the parameter name and schema constraints. It therefore fails to compensate for the low 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 uses a specific verb 'List' and identifies the resource 'sourcing requests' along with the scope 'owned by the authenticated buyer organization across API keys and OAuth agents'. This clearly distinguishes it from sibling tools like get_sourcing_request and submit_sourcing_request.

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 when to use the tool: when you need recent sourcing requests for the authenticated buyer org across both API keys and OAuth agents. It does not mention alternatives or exclusions, so it earns a 4 rather than 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=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context by specifying that only merchant-confirmed orders are included and that related RFQ/quote/plan/checkout artifacts are not orders, which helps set return expectations. It goes beyond the annotations by clarifying the operational scope.

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 primary action and followed by a clear exclusion list. No redundant 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?

Given the zero-parameter simplicity and presence of an output schema, the description adequately conveys the tool's purpose and boundary. It explains what is returned (merchant-confirmed orders attributable to supplier) and what is not, making it complete for selection and 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?

Tool has zero parameters, so schema description coverage is 100% with no gaps. The description doesn't need to explain parameter semantics because there are none.

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

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

Specific verb 'List' plus resource 'merchant-confirmed orders attributable to the authenticated supplier' clearly defines scope. Explicitly excludes RFQs, quotes, plans, and checkout handoffs, distinguishing it from sibling tools like list_supplier_rfqs or get_checkout_handoffs.

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?

Provides clear context: it's for merchant-confirmed orders for the authenticated supplier. The exclusion of RFQs, quotes, plans, and checkout handoffs implicitly tells the agent to use other tools for those document types. However, it does not explicitly name alternative tool names, so not 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds that a supplier API key is required and that only approved RFQs are returned. This is useful behavioral context about authentication and filtering.

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

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

The description is two short, front-loaded sentences with no filler. Every word adds value, and the structure is easy to scan.

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

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

Given the simple single-parameter tool, strong annotations, and existing output schema, the description is mostly complete. It covers authentication and scope; only minor details like pagination behavior could be added, but they are not essential.

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

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

The schema has zero description coverage, and the tool description does not explain the 'limit' parameter. Even though limit is common, the description fails to compensate for the lack of schema descriptions, leaving the agent to infer behavior from the parameter name alone.

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 states the tool lists approved RFQs matched to the authenticated supplier. It uses a specific verb ('list'), identifies the resource (RFQs), and specifies scope ('approved' and 'matched to the authenticated supplier'), distinguishing it from related tools like get_supplier_rfq.

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 usage context: this is for suppliers retrieving their own approved RFQs, and it notes the requirement of a supplier API key. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough.

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, so the safety profile is covered. The description adds useful context beyond annotations: it specifies the 'public' nature of the directory and the inclusion of 'verified supplier counts,' which informs the agent about data provenance and output characteristics.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the action, resource, scope, and an output detail.

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 tool has no parameters, an output schema exists (as per context signals), and the description covers the core return value (categories and supplier counts), the description is complete for this simple retrieval 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics because there are none; the schema coverage is 100% (empty properties).

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 states the verb 'List' and the resource 'product categories' with a specific scope: 'the public industrial compressor service-parts supplier directory.' It also mentions an additional output detail ('including verified supplier counts'), distinguishing it from sibling tools like list_sourcing_categories.

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 usage context by clearly stating what it returns, but it does not explicitly say when to use this tool versus alternatives or mention exclusions. For a simple no-parameter list tool, this implicit guidance is adequate but not 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 indicate non-read-only, open-world, non-idempotent behavior. The description adds valuable specifics: it 'records the claim and notifies the supplier' and explicitly states it does 'not assert eligibility or approval,' which goes beyond the annotations.

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

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

The description is two sentences with the main action front-loaded and a concise behavioral nuance following. Every word earns its place, with no redundancy or 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?

The description covers the purpose, target, and side effects effectively. With an output schema present, it does not need to explain return values. It omits explicit mention of required parameters, but that detail is already in the schema, making the description adequately complete.

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

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

With 0% schema description coverage, the description partially compensates by implying order_id refers to an accepted order and order_item_id to a specific line. However, it provides no semantic detail for the required 'description' parameter, leaving its purpose to be inferred.

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 the specific verb 'open' with the resource 'durable warranty claim' and clearly identifies the target as 'an accepted order or specific order line.' This distinguishes it from sibling tools like update_supplier_warranty_claim and request_order_return.

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 provides clear context for when to use the tool: on an accepted order or specific order line, and clarifies it does not assert eligibility or approval. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full 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 convey safety traits (readOnlyHint=false, destructiveHint=false). The description adds value by disclosing additional behavioral details: it notifies the supplier-side organization, records owner/status/event history, and does not claim a resolution. These specifics go beyond the structured annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds useful information. It is efficient and free of 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?

The description captures the tool's purpose and side effects, and the presence of an output schema reduces the need to explain returns. However, with five parameters and no parameter-level guidance, the description is not fully complete. It is minimally sufficient but leaves the agent to infer parameter details solely from names and enums.

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

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

With schema description coverage at 0%, the description must compensate for the lack of parameter explanations, but it does not. It merely references 'order' generically without mentioning order_id, issue_type, summary, owner_type, or order_item_id. The agent receives no guidance about how to populate these required 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 clearly states the tool's action ('Open'), the resource ('durable post-purchase issue'), and the context ('for a merchant-confirmed order'). It also clarifies what it does NOT do ('does not claim a resolution'), distinguishing it from resolution-oriented siblings like update_supplier_order_issue.

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 by specifying 'post-purchase' and 'merchant-confirmed', but it does not explicitly name alternatives or state when not to use it. The mention of 'notifies the supplier-side organization' and 'does not claim a resolution' provides contextual guidance about its role compared to returns or cancellations.

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 important behavioral traits beyond annotations: it creates a request and notification, and it never reports the order as cancelled until acceptance. This adds context about side effects and state changes that the annotations (readOnlyHint, destructiveHint) do not fully capture.

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 only two sentences, with no filler. The first sentence states the action and scope, the second clarifies the non-destructive nature, making every word meaningful.

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 tool with only two simple parameters and an output schema, the description adequately covers the primary action and the key nuance that cancellation is not immediate. It lacks explicit prerequisites (e.g., order ownership) but is sufficiently complete for its complexity.

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

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

The input schema has 0% description coverage, and the description provides no information about order_id or reason. The parameter names are self-explanatory, but the description does not add meaning or constraints beyond what the schema already contains, failing to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool asks the merchant to cancel an unshipped order, using the specific verb 'ask' and identifying the resource and scope. It distinguishes itself from sibling tools like decide_supplier_order_cancellation by explicitly framing it as a request that does not finalize cancellation.

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 when to use the tool: for unshipped orders, and it clarifies that it only creates a request. It does not explicitly name alternatives or add exclusions, but the 'never reports as cancelled' clause effectively differentiates it from the supplier-side decide 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?

The description adds context beyond annotations by disclosing that the supplier remains merchant of record and controls authorization and refund state. This clarifies the tool's non-finalizing nature and that the request may be pending. Annotations already indicate a write, non-idempotent, non-destructive operation, but the description enriches the behavioral profile without 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?

The description is two sentences, immediately states the action, and contains no filler. The first sentence front-loads the verb and resource, while the second adds a relevant clarification about supplier control. Every word 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?

The description covers the core purpose and a key behavioral aspect (supplier control of authorization/refund), which helps the agent understand the outcome. However, it omits guidance on the items parameter and the meaning of 'open' in terms of order status, leaving some ambiguity. The presence of an output schema compensates for return value details but not parameter semantics.

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 description provides no information about the parameters (order_id, reason, items). With schema description coverage at 0%, the description must compensate, but it offers no explanation of what 'reason' should contain, whether 'items' is optional, or how quantities are specified. This is a significant gap for an agent constructing the call.

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 states the tool's function: 'Open a return request after shipment.' It uses a specific verb (open) and resource (return request), and the context 'after shipment' distinguishes it from pre-shipment cancellations like request_order_cancellation. This clarity helps differentiate from sibling tools.

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

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

The description provides a clear usage condition: 'after shipment' indicates when this tool should be used. It does not explicitly mention alternatives or exclusions, but the post-shipment context and the note that the supplier controls authorization imply it is for initiating, not finalizing, returns. This is sufficient for basic 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 and idempotentHint=false, so the agent knows it's a side-effecting action. The description adds valuable context by specifying what the link is bound to (plan version, suppliers, etc.) and clarifying that it does not perform final approval or purchase. This extra boundary information goes beyond the annotations, though it doesn't cover prerequisites or 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?

The description is two sentences, succinct and front-loaded. The first sentence immediately states the action and scope; the second eliminates ambiguity about side effects. Every word contributes value with no redundancy.

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

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

For a tool with only 2 parameters and an output schema, the description is quite complete. It covers the action, the object, binding details, and explicitly states non-actions. Minor gaps include missing prerequisites (e.g., verifying the plan exists) and how to retrieve/use the generated link, but these are not critical given the schema and sibling tools.

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

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

With schema description coverage at 0%, the description should compensate for parameter documentation, but it does not. It neither explains purchase_plan_id nor expires_in_minutes beyond what the schema shows (types, defaults, min/max). The mention of 'expiry' hints at the expiration parameter but does not directly describe it. Parameter names are self-explanatory, but the description fails to add meaning beyond the schema.

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

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

The description uses a specific verb ('Create') and a specific resource ('human review link'), and clearly defines the scope ('bound to the exact purchase-plan version, suppliers, maximum amount, currency, risks, and expiry'). It also distinguishes itself by explicitly stating what it does not do ('does not approve or purchase the plan'), which sets it apart from related tools like create_purchase_plan.

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 the use case: requesting human approval for a purchase plan. It includes an explicit exclusion ('does not approve or purchase the plan') which clarifies when not to use it as a final action. However, it does not name alternative tools or provide explicit 'use this when' statements, 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?

Beyond the annotations, the description adds key behavioral traits: revisions are immutable, the previous revision remains in history, and the new one becomes current. These are non-obvious and not covered by readOnlyHint/destructiveHint, making the behavior transparent and trustworthy.

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

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

Two sentences, front-loaded with the core action and key behavior. Every word adds value; there is no fluff 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?

The description covers the high-level revision semantics but omits any explanation of required inputs (match_id, quote_id, currency, items). While an output schema exists, the agent still needs to understand what each input represents. The complexity (13 params) makes the description incomplete without parameter guidance.

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

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

With 0% schema description coverage, the description carries the burden of parameter meaning, but it does not mention any parameters. The only hint is the phrase 'supplier quote,' which weakly maps to quote_id, but does not clarify match_id, items, currency, or other crucial fields. This is insufficient compensation for the missing schema descriptions.

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

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

The description clearly states the action ('Create a new immutable revision') and the resource ('supplier quote'). It distinguishes this from a simple submit operation by explicitly noting the revision behavior, which helps differentiate from the sibling 'submit_supplier_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?

The descriptor implies this tool is for revising an existing supplier quote, as it says 'new immutable revision' and 'previous revision remains in history.' It does not explicitly state when not to use it or mention alternatives, but the functional intent is clear from 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?

With readOnlyHint and destructiveHint annotations covering the safety profile, the description adds useful behavioral context: results retain provider, observation time, and merchant URLs, and no checkout/order is created. This goes beyond the annotations by describing output characteristics and confirming side-effect-free 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 that efficiently conveys what the tool does and its key side-effect boundary. No wasted words or repetition of schema details.

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 covers the core purpose and the no-order boundary, and the output schema likely explains return values. However, it leaves parameter semantics completely unaddressed, making it less complete for a tool with 0% schema description coverage. Adequate but with clear gaps.

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

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

Schema description coverage is 0% for 4 parameters, yet the description provides no parameter-level guidance. It does not explain the meaning of 'query', 'limit', 'search_type', or 'manufacturer', nor the difference between part_number and keyword search. The description fails to compensate for the schema's lack of descriptions.

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

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

The description clearly states the tool searches for electronic-component data (product, availability, lead-time, price) from Mouser, using the verb 'search' and a specific resource. It also distinguishes itself from transactional tools by clarifying that no checkout or order is created.

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: this is for retrieving live, attributed component data from Mouser, with no order side-effect. It does not explicitly name alternatives like 'search_products', but the negative boundary ('no checkout or order is created') helps disambiguate from order-related tools.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by disclosing that commercial price, stock, compatibility, and lead time are returned only when supported by current evidence. This informs the agent about the tool's selective output behavior, adding useful context.

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, focused sentence that efficiently states the tool's purpose and a key behavioral caveat. No filler or repetition exists, 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?

While the description clearly states the core functionality and an important behavioral nuance, it omits any guidance on parameters, making it incomplete for effective tool usage. Given the presence of an output schema and annotations, this is acceptable but leaves clear gaps for an agent to fill via heuristics.

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

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

With 0% schema description coverage, the description needed to explain the parameters (q, limit, category, manufacturer) but makes no mention of them. It does not compensate for the schema gap at all, leaving the agent to guess at the meaning and usage of each parameter.

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

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

The description clearly states the tool's action (search) and resource ('published canonical product facts'), distinguishing it from sibling tools like search_suppliers and search_live_components. It also adds a scoping note about which product facts are returned, reinforcing its 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?

The description provides no explicit guidance on when to use this tool versus alternatives such as get_product or search_suppliers. The term 'canonical' implies authoritative product data, but no alternatives or exclusions are mentioned, leaving the agent without clear decision criteria.

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

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

Annotations already cover read-only, idempotent, and non-destructive behaviors. The description adds value by disclosing that no authentication is required and that profiles are 'source-backed public,' providing context beyond the annotations without 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?

The description is a single, front-loaded sentence that immediately states the verb and object, then lists the search facets and ends with a critical usage note. No wasted words.

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 schema's detailed parameter definitions and an output schema, the description is sufficient for an agent to select and invoke the tool. It could mention pagination or default country, but those are already documented in the schema, so the description's brevity is acceptable.

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

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

The description lists the searchable dimensions (product category, brand, company type, service, compressor type, industry, text), which maps to most of the parameters and adds meaning beyond the schema's 40% individual field descriptions. Limit and offset are conventional and need no additional explanation.

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 states the action ('Search') and the resource ('source-backed public supplier profiles'), and enumerates the specific search dimensions (product category, brand, company type, service, compressor type, industry, text). This distinguishes it from sibling tools like search_products or get_supplier.

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: it searches public, source-backed supplier profiles and explicitly notes 'No authentication required.' However, it does not name alternative tools or specify when not to use this tool, keeping it a step below the highest bar.

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?

Description explicitly states 'does not contact suppliers' and that 'a human operator must approve every outbound recipient, message, and artifact scope.' These are critical behavioral disclosures that go beyond the provided annotations (which are absent). It also implies side effects like locking the revision and creating request lines, making the mutation behavior clear.

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: first states the action and outcome, second states an important behavioral boundary. Front-loaded with the main verb and outcome, then a critical caveat. No fluff or redundant phrases.

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 no annotations and no output schema, the description adds safety and scope context but lacks specifics like parameter behaviors (e.g., need_by format, substitutions_allowed implications), the meaning of 'validated project revision', or how returned candidates are structured. With 10 parameters and 18% schema description coverage, it should clarify which parameters affect behavior, especially the items array vs. auto-derived BOM lines. The description is adequate for a high-level purpose but incomplete for nuance.

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

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

Schema coverage is only 18%, so the description must compensate. It surfaces the key parameter semantics: 'create normalized request lines', 'return supplier candidates', and the critical constraint of human approval on recipients/messages. While not exhaustive, it adds meaningful context beyond the schema (e.g., that items is optional and 'sources the current BOM'). The description also clarifies that the tool is about the sourcing package, not just generic searching.

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 states what the tool does: lock a validated project revision, create sourcing lines, and return supplier candidates. It uses specific verbs ('Lock', 'create', 'return') tied to the resource ('immutable sourcing package'), and the qualifier 'validated project revision' differentiates it from siblings like submit_sourcing_request.

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 does not mention when to use this tool versus alternatives such as submit_sourcing_request or revise_supplier_quote. It also fails to state prerequisites like 'project must be validated' or whether it should be called before/after other tools. The only implicit guidance is that it creates a package and returns candidates, which is insufficient.

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 behavior beyond the annotations: the request is supplied to relevant suppliers, the action produces a later decision, and a buyer API key is required. This is useful because the annotations only say the operation is not read-only, not destructive, and appears idempotent; they do not communicate the real-world routing side effect.

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 compact and front-loaded. It consists of three short sentences that respectively state the action, the after-effect, and the auth prerequisite. No fluff or redundancy.

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

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

Given the rich schema, annotations, and output schema, the description provides sufficient top-level context: purpose, routing behavior, asynchronous decision outcome, and API key requirement. Context around idempotency, fixture_kind, or data_classification is not repeated, which is acceptable because those are already present in the schema or annotations.

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

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

The description adds no parameter-specific guidance. With 10 parameters and only 50% schema description coverage, parameters like notes, substitutions_allowed, ship_to_postal_code, part_number, and manufacturer are left without helpful context, and the tool description does not compensate for that gap.

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

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

The description clearly identifies the action with a specific verb and resource: 'Submit a real non-sensitive B2B sourcing request on behalf of the buyer.' It also specifies the overall workflow by saying SupplySlate routes it to suppliers and returns a decision later, which differentiates it from sibling tools that list, get, quote, or otherwise manage sourcing data.

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 direct context for when to use the tool: for real, buyer-side, non-sensitive sourcing requests, and with a buyer API key. It does not explicitly compare to alternatives such as submit_supplier_quote or source_project, but the buyer-side action is distinct enough in this toolset.

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 indicate a write operation (readOnlyHint=false) and no destructive effects. The description adds valuable context: money must be in integer minor units with explicit currency, partial line coverage is allowed, and labeled alternatives are permitted. This goes beyond the annotations and clarifies behavioral expectations.

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 only two sentences and each sentence earns its place. It front-loads the purpose and then states critical constraints, with no wasted words or repetition of schema details.

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 tool's complexity (12 parameters, nested items) and the presence of an output schema, the description does not need to explain return values. It covers the essential purpose, precondition (human-approved RFQ), and key structural rules (money units, partial coverage, alternatives). A minor gap is not explicitly pointing to revise_supplier_quote for subsequent quotes, but 'first' implies this.

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%, but the description clarifies that money fields use integer minor units and that partial line coverage/labeled alternatives are allowed, which maps to items and relationship fields. However, it does not explain many top-level parameters (match_id, notes, terms) beyond their schema names, which are self-descriptive but not elaborated.

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 states a specific action and object: submitting the first structured commercial quote for a human-approved RFQ. The word 'first' distinguishes it from sibling revise_supplier_quote, and 'human-approved' provides a clear context.

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 usage conditions: it is for the first quote and only for human-approved RFQs. However, it does not explicitly name alternatives like revise_supplier_quote or state when not to use it, so it stops short of a full 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 indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable context by explicitly stating the operation 'without rewriting historical snapshots', which clarifies that previous availability data is preserved. This is an important behavioral trait beyond what annotations provide.

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

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

The description is a single, compact sentence that front-loads the primary verbs and resource. Every phrase contributes meaning: 'Append timestamped', 'update current catalog state', 'by supplier SKU', 'without rewriting historical snapshots'. There is no redundancy or wasted words.

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 complexity of the input schema (array of up to 500 items with detailed properties), the description provides the core behavioral model and the key guarantee of not rewriting history. The existence of an output schema and a well-structured input schema reduce the burden on the description, but it still does not mention item limits, status values, or potential failure modes.

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

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

The schema has a rich structure (items array with required supplier_sku, status, observed_at, plus optional fields), but the description only hints at 'by supplier SKU'. With 0% schema description coverage, the description fails to explain the array structure, the meaning of statuses, or the timestamping mechanism, leaving the agent reliant solely on 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 clearly states the tool's purpose: to append timestamped supplier availability evidence and update current catalog state, scoped by supplier SKU. It uses specific verbs (append, update) and resources (supplier availability evidence, catalog state), and the mention of preserving historical snapshots distinguishes it from sibling update/upsert tools.

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

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

The description implies when to use the tool: when you have timestamped availability observations to append and want to update the current state without overwriting history. However, it does not explicitly exclude alternatives like update_supplier_catalog or upsert_supplier_catalog, nor does it list 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 says 'Replace' which implies overwriting and thus destruction of the old requirement set, but the annotations set destructiveHint=false. This is a direct contradiction. The description does add the 'unlocked' precondition and explains the confirmed flag, but the contradiction forces a score of 1.

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 extremely concise: two sentences, 20 words. It front-loads the main purpose and adds one clarifying detail. Every sentence serves a purpose.

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 complex update operation with a nested requirements array and no safety annotations, the description is too sparse. It does not mention the return value, error conditions, validation behavior, or permission requirements. It only gives the 'unlocked' prerequisite and a meaning for one field. The output schema exists but is not provided, so the description must carry more weight.

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%. The description only clarifies the meaning of the 'confirmed' flag within the requirements array, but does not explain project_id or other requirement fields. It fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the action (Replace), the resource (structured requirement set), and a key condition (on an unlocked project revision). This is specific and distinguishes it from other project tools like get_project or validate_project.

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

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

The description gives a clear prerequisite by stating the operation targets an unlocked project revision. However, it does not explicitly compare with alternatives or state when not to use the tool, 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?

The description discloses that the operation replaces the supplier-submitted set while preserving separately sourced evidence, which is meaningful side-effect context beyond the all-false annotations. It does not mention auth, rate limits, or reversibility, but the primary mutation scope is clear.

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 sentence that is front-loaded with the action and resource, with no wasted words or redundant 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?

Given a complex nested input schema with no field descriptions and no usage alternatives, the one-sentence description is insufficient for an agent to confidently construct a valid capabilities payload. It does not explain how to represent capabilities or what happens to existing data beyond 'replace'.

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 explain the 'capabilities' array structure, required fields, or the meaning of nested fields like capability_type, normalized_value, or evidence_excerpt. The phrase 'capability set' only loosely maps to the parameter.

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

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

The description uses the specific verb 'Replace' and names the resource 'supplier-submitted capability set', with a key preservation constraint. This clearly distinguishes it from sibling tools like update_availability or upsert_supplier_catalog.

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 the tool is for replacing supplier-submitted capabilities, but it does not explicitly state when to prefer it over alternatives or when not to use it. No sibling comparisons or exclusions are provided.

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 this is a non-read-only, non-idempotent operation, and the description adds valuable behavioral context: 'State transitions and order-item quantities are validated and audited.' This tells the agent that invalid status changes will be rejected and that changes are logged. It does not disclose failure modes or permission requirements, but with annotations covering the basic safety profile, this is acceptable.

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 concise sentences with no filler. The first sentence states the core action and optional shipment behavior; the second adds validation/audit context. It is well-structured 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?

Despite the tool's complexity (nested shipment object, status enum, 4 parameters), the description does not specify allowed state transitions, when the shipment object should be provided, or how statuses relate to fulfillment stages. The presence of an output schema covers return values, but the description leaves critical usage context unanswered for an agent invoking this tool.

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

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

Schema description coverage is 0%, and the description only indirectly references parameters via 'optionally recording a shipment.' It does not explain the meaning of status values, the order_id format, or the contents of the shipment object, leaving the agent to infer from property names and enums alone. Since schema coverage is zero, the description fails to compensate, making this dimension weak.

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 states the tool's function: 'Acknowledge or update fulfillment on a merchant-confirmed supplier order, optionally recording a shipment.' It specifies the verb (update), resource (supplier order), and key sub-behavior (shipment recording), which distinguishes it from sibling tools like update_supplier_order_issue or request_order_cancellation.

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 the order must be 'merchant-confirmed' but does not explicitly state when to use this tool versus alternatives such as request_order_cancellation or update_supplier_order_issue. It provides context (fulfillment updates) but no exclusions or alternative tool guidance, so usage guidance is only partially 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 indicate a non-read-only, open-world, non-idempotent operation. The description adds context about the specific fields updated and the scope (authenticated supplier's merchant order), which goes beyond the annotations. It does not detail open-world side effects, but the openWorldHint annotation covers that risk.

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 sentence, front-loaded with the verb 'Update', and contains no unnecessary words. It efficiently conveys the core action and scope.

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 has an output schema and clear annotations. The description covers the main action and scope but lacks mention of prerequisites or subtle behavioral constraints. For a moderately complex tool, this is adequate, though it could benefit from noting any state dependencies for issue resolution.

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

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

With 0% schema description coverage, the description must compensate. It mentions 'ownership, status, or resolution' which maps to owner_type, status, and resolution parameters, but does not explain the enum semantics or elaborate on order_id/issue_id. The schema's patterns and enums provide the necessary detail, so the description adds marginal value.

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 action (update) and the resource (buyer-reported issue on the authenticated supplier's merchant order), and lists the specific fields (ownership, status, resolution). This distinguishes it from sibling tools like report_order_issue (create) and update_supplier_order (order-level 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 provides clear context on when to use the tool: for buyer-reported issues on the supplier's merchant order. However, it does not explicitly state when NOT to use it or mention alternative tools, such as report_order_issue for creating issues or update_supplier_order for order-level changes.

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 that the operation is not read-only, not idempotent, and not destructive. The description adds a useful behavioral detail—'without changing historical order evidence'—which is beyond the annotations. However, it does not disclose other important traits such as side effects on related records, reversibility, or preconditions beyond 'authenticated'.

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, well-structured sentence that front-loads the primary action and includes a key constraint. Every word adds meaning, with no redundant or filler content.

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

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

Given the tool's complexity (7 parameters, mutation, status transitions, financial fields), the description is too sparse. It provides a high-level purpose and one constraint, but lacks guidance on parameter relationships, when the tool should be used, or how it handles the six statuses (including rejected/cancelled). The presence of output schema helps, but it does not compensate for the missing operational 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?

With 0% schema description coverage, the description must compensate for explaining parameters, but it only indirectly references status states (authorized, shipped, received, refunded). It does not explain required identifiers order_id and return_id, nor does it clarify fields like refund_amount_minor, currency, or merchant_return_reference. The status enum in the schema covers possible values, but the description adds minimal semantic value.

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 the specific verb 'Advance' and clearly identifies the resource as a supplier return, describing the lifecycle states (authorization, shipment, receipt, refund). This distinguishes it from sibling tools like update_supplier_order and request_order_return, making the tool's 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 usage for progressing a supplier return through its status lifecycle, but it does not explicitly state when to use this tool versus alternatives like update_supplier_order or decide_supplier_order_cancellation. No exclusions or alternative recommendations are provided, so the guidance remains implicit rather than explicit.

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