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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is a dangerous deletion requiring an environment flag and confirmation, but it omits critical details such as irreversibility, side effects on related records, and what happens if confirmation is false or absent.

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

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

Two short sentences with zero waste; the method, path, and gating requirements are front-loaded. Every clause earns its place for a minimal delete tool.

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 destructive tool with no annotations and no output schema, the description is too thin. It covers the gating requirements but says nothing about permanence, side effects on related data, or error behavior, leaving an agent without enough context to call it safely in a production workflow.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that `confirm` must be true, adding meaning beyond the schema's default false, and the path placeholder {number} shows where the required customer identifier goes. It does not document the `number` constraints (pattern, max length) or the full semantics of `confirm` (e.g., what happens on false).

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

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

States a specific verb (DELETE) and resource (/customer/{number}), making the action unmistakable. It does not explicitly distinguish itself from sibling tools like delete_customer_product, but the resource path is clear enough for an agent to select it.

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 prerequisite conditions (AIOTIC_MCP_ALLOW_DANGEROUS=true and confirm:true), which imply this tool should only be used when dangerous operations are enabled and confirmation is supplied. However, it does not describe when to use this versus alternatives such as delete_customer_product, nor does it mention 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?

With no annotations, the description carries the full behavioral burden. It does disclose that this is a destructive DELETE gated behind an environment flag and confirmation, which is genuinely useful. It does not describe irreversibility, side effects on related records, or error behavior when the gate is off.

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

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

Two short sentences, zero filler, with the operation and its safety gate front-loaded. Every clause earns its place.

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

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

There is no output schema, so the description would ideally note the return/confirmation behavior, and it doesn't. It covers the operation and its gating prerequisites adequately, but a destructive tool with three undocumented parameters and no annotations should say more about consequences.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for confirm (must be true to proceed, matching the schema default of false) and implies the two path parameters via the URL template. It does not explain the customer_number/customer_item_number format or pattern 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 gives a concrete verb+resource through the HTTP route DELETE /customer-product/{...}, so an agent can tell it removes a customer-item mapping. It is clear but does not explicitly distinguish itself from siblings like upsert_customer_product or delete_customer beyond the route name.

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

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

It states a prerequisite (AIOTIC_MCP_ALLOW_DANGEROUS=true and confirm:true), which implies 'only use in a danger-enabled session'. However, it never says when to choose this over alternatives such as upsert_customer_product, nor any exclusion conditions.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the critical dangerous-operation gate and confirmation requirement. It stops short of stating irreversibility, whether related customer-product links cascade, or what the response/error looks like when the flag is missing.

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 terse sentences with the destructive gate front-loaded after the endpoint identity; no filler and no repetition of the title.

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 dangerous mutation with zero annotations, no output schema, and 0% schema coverage, the definition covers the invocation gate and parameter identity but leaves out blast radius, reversibility, and auth expectations. It is minimally sufficient to call safely but not complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it addresses all three parameters: item_number and language_code are shown as identity path segments, and confirm is stated to require true rather than the schema's misleading default of false. It adds no format constraints, but the semantics it supplies are the ones an agent actually needs.

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

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

The description states the HTTP verb and path, which confirms the resource being deleted, but it largely restates the name 'delete_product' rather than describing what deletion means for a product. It offers no differentiation from siblings such as delete_customer_product or upsert_product, so an agent must infer the distinction from names alone.

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 a concrete precondition for invocation (AIOTIC_MCP_ALLOW_DANGEROUS=true and confirm:true), which is actionable. However, it gives no when-to-use guidance relative to alternatives like upsert_product or delete_customer_product, and no statement of what happens if the gate is not satisfied.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not whether the call is read-only (implied only by 'GET'), not permission requirements, not rate limits, and not the failure mode when the customer number does not exist.

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

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

It is short, but this is under-specification rather than earned conciseness. A single bare route fragment leaves the reader with nothing front-loaded except the HTTP verb.

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

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

With no output schema, no annotations, and an undocumented required parameter, the description should explain what a successful lookup returns and what happens on a miss. None of that is present, so the definition is inadequate for even a simple lookup 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 single parameter is shown only as the path placeholder {number}, which merely echoes the schema property name. With 0% schema description coverage, the description should explain that this is an exact customer identifier, but it adds no format, example, or meaning beyond the route template.

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 is essentially the tool name restated as an HTTP route: 'GET /customer/{number}.' It conveys retrieval of a customer keyed by number, but adds no verb/resource framing beyond what the name and title already state, and does nothing to separate it from siblings like search_customers or get_customer_product.

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

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

There is no when-to-use guidance, no mention of the sibling search_customers for non-exact lookups, no prerequisites, and no exclusions. The agent is left to infer everything about selection from the tool 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?

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: schemas are inlined, so the response is self-contained and potentially large. It says nothing about behavior on an unresolvable ref, error semantics, or explicitly that it is a read-only lookup.

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, front-loaded with the core purpose and followed by the three identifier formats. Every example earns its place by removing ambiguity about the ref argument.

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

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

For a one-parameter read lookup with no output schema, the description covers the input contract and the shape of the return ('schemas are inlined') adequately. The remaining gap is routing guidance against the many sibling lookup 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?

Schema description coverage is 0% and the single 'ref' parameter is undocumented in the schema, so the description must compensate — and it does, naming three accepted identifier forms (operationId, "METHOD /path", webhook name) with concrete examples. Only the length bounds (2–160) go unmentioned.

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

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

States a specific verb and resource ('Full contract of one endpoint') and pins down exactly what the tool returns ('schemas are inlined'). This distinguishes it from siblings like list_endpoints (enumeration) and get_schema (component schema), which an agent can infer without opening a schema.

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

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

Usage is implied by the examples of accepted identifiers, but the description never states when to reach for this tool versus list_endpoints (to discover refs) or get_schema/get_example (for pieces of a contract). No prerequisites or exclusions are given.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that samples are 'real' (not synthetic), but says nothing about what happens on an unrecognized name, whether the list is exhaustive, output format, or any access constraints.

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

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

Two compact fragments with the core purpose front-loaded before the value list. Nothing is wasted, though the trailing list is a bare run-on with no per-name explanation of what each sample contains.

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 single-parameter read tool with no output schema, the agent still lacks any indication of the return shape or the meaning of each sample name. The enumerated names cover the input side adequately but leave the output side to inference.

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

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

Schema coverage is 0% and the single 'name' parameter has no enum, so the description does the heavy lifting by enumerating ten valid sample names. This effectively supplies the missing value domain, though it does not state whether the list is complete or case-sensitive.

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

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

The description states the resource plainly ('Real payload samples') and the title adds the verb ('Get a payload example'), so an agent understands it retrieves example payloads. It is clear but does not differentiate itself from siblings like get_schema or get_endpoint, which could also be read as returning structural samples.

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

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

There is no when-to-use or when-not guidance and no routing to alternatives. The enumerated names imply the tool is keyed by sample type, but nothing tells the agent why to pick this over get_schema or get_page when it wants example data.

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

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

No annotations are provided, so the description carries the full burden, and it discloses nothing beyond 'GET'. It says nothing about whether the operation is a safe read (implied but unstated), what it returns, error behavior for an unknown email_group_id, or any permission requirements.

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

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

The single sentence is short but is under-specification rather than conciseness; it is not front-loaded with any useful information and reads as a machine-generated route stub rather than an instruction.

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

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

With no annotations, no output schema, and an undocumented parameter, the description should do substantial work but instead provides only the route. It is entirely inadequate for an agent to invoke the tool confidently.

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

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

There is one parameter with 0% schema description coverage, and the description adds no meaning beyond echoing the path placeholder. The uuid format is only conveyed by the schema's format field, and the description contributes no semantics for email_group_id.

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

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

The description is a raw HTTP method and path ('GET /order/group/{email_group_id}') that largely restates the tool name get_order_group. It hints at retrieving an order/email group but does not state a specific verb+resource in prose or distinguish it from siblings such as get_order_status or get_customer.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of any alternative among the many sibling tools. The agent is given nothing to route on beyond the endpoint string.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the read-only nature via the GET verb and lists the returned fields (status, result, erp_ref, errors), which is real value with no output schema present. However, it says nothing about auth requirements, rate limits, whether status is terminal, or how errors are surfaced, leaving meaningful behavioral gaps for a no-annotation tool.

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

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

A single compact line, front-loaded with the endpoint and followed by the payload contents; nothing is padded. The em-dash fragment style is terse but readable.

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

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

With no output schema, the field enumeration is a useful stand-in, but a status-checking tool with zero annotation coverage and an undocumented identifier parameter should say more about lifecycle semantics, error handling, and retry/polling expectations. It is adequate but leaves 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?

There is one parameter with 0% schema description coverage, so the description must compensate. It only echoes request_id inside the path template, implying it is a path identifier, but adds no meaning about where the request_id originates (e.g., from upload_order) or what form it takes beyond the uuid format already 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 names a specific verb and resource ('GET /order_status/{request_id}') and enumerates what comes back (status, result, erp_ref, errors), so the agent knows exactly what the tool retrieves. It does not explicitly contrast itself with siblings like list_orders or get_order_group, which keeps it out of 5 territory.

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

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

There is no statement of when to call this versus alternatives such as list_orders or retry_order, and no prerequisite or polling guidance. The agent must infer usage entirely from the name and path.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses the output format (Markdown) and gives example path shapes, but says nothing about error behavior for invalid paths, authentication/permission requirements, or whether the guide content is versioned. Adequate but incomplete for an annotation-free tool.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the path-format/routing hints following in priority order. Every sentence earns its place.

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

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

For a single-parameter read tool with no output schema, the description covers what it returns (Markdown), the input shape, and how to discover inputs. Only edge-case behavior (invalid path, auth) is absent, which is a minor gap given the tool's simplicity.

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 schema only declares a 1-120 char string — so the description must compensate, and it does by giving concrete path examples ('/receiving/erp-receive-endpoint', '/sdk/pipeline') that reveal the leading-slash hierarchical format. It stops short of stating constraints like the 120-char limit or case sensitivity.

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

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

The description states a specific verb and resource ('Return one guide page') plus the return format ('as Markdown'), which immediately separates it from content-discovery siblings like list_pages and search_guide. An agent can tell what this tool produces without opening the schema.

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

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

It gives explicit routing guidance for one sibling: 'Use list_pages to discover paths,' which tells the agent how to obtain a valid input. It does not address when to prefer search_guide or what to do when a path is unknown, so it stops short of full when/when-not coverage.

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

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

No annotations are provided, so the description bears the full behavioral burden, yet it only conveys the HTTP verb GET, implying a non-destructive read. It says nothing about authentication, error behavior for unknown item numbers or language codes, localization fallback, or return shape.

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

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

It is short but under-specified rather than concise: a single fragment with a trailing period and no human-readable sentence. Brevity here reflects missing content, not efficient expression.

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

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

With no annotations, no output schema, no parameter descriptions, and no guidance, the definition is completely inadequate for an agent to call this tool correctly in a crowded sibling set. Only the bare route is conveyed.

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 both parameters are undocumented in the schema. The route template does show the parameter names and that they are path-segment parameters, but adds no meaning beyond that — e.g. no format, accepted language codes, or case sensitivity.

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 is essentially a raw route template that restates the tool name ('Get product') plus the path. It does imply a read of a single product, but offers no statement of what a 'product' resource contains or how it differs from siblings like list_products or get_customer_product.

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

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

There is no guidance on when to use this tool versus the many siblings. Nothing distinguishes it from list_products (bulk listing) or get_customer_product (customer-scoped view), and no preconditions are stated.

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

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

With no annotations, the description carries the full burden, and it does disclose a real behavioral trait beyond the schema: that $refs are inlined rather than left as references, which affects how the agent consumes the result. It still omits error behavior for unknown names and says nothing about caching, but for an obvious read lookup this is solid disclosure.

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

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

Purpose and the key $refs-inlining detail are front-loaded before the name list. The long enumeration is verbose but functional, since it substitutes for the missing schema documentation; it earns its space rather than being 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?

There is no output schema or annotations, so the description must stand alone; it covers the parameter domain completely and characterizes the return value ('JSON schema ... with $refs inlined'). Only error/edge-case behavior on an invalid name is left unaddressed, which is minor for a simple read lookup.

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

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

Schema description coverage is 0% and the schema only declares name as a bounded string, but the description compensates by fully enumerating the 48 valid component names, effectively supplying the enum the schema lacks. It does not clarify any name semantics beyond the self-descriptive identifiers.

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

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

The description gives a specific verb and resource ('One JSON schema from the API components') and adds a meaningful qualifier ('with $refs inlined') that distinguishes it from sibling lookups like get_endpoint, get_page, or get_example. An agent can immediately tell what it retrieves without opening the schema.

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

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

The purpose implies when to use it (you need a named component schema), but the description offers no explicit when/when-not guidance or alternative routing (e.g., vs get_endpoint or search_guide). Usage is inferable from the name and enumeration rather than stated.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does reveal the taxonomy it returns (sendable / landed / terminal plus transitions), which is useful reference content, but it never states that this is a side-effect-free, static lookup with no inputs, nor does it describe the shape of the returned transitions. For a zero-annotation tool this is partial coverage.

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

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

A single, front-loaded fragment with no filler. It is efficiently sized, though the fragmentary phrasing slightly reduces immediate comprehension compared with a full sentence.

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

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

With no parameters, no annotations, and no output schema, the description is the only source of information about the return value. It names the status categories but does not explain the transition structure, whether the list is exhaustive, or how an agent should interpret 'sendable'. Adequate as a pointer, incomplete as a specification.

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 defines zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter meaning is missing.

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 communicates the subject matter: the set of status values (sendable/landed/terminal) and the transitions between them. However, it is a noun phrase rather than a clear statement of what the tool returns, and it never explicitly distinguishes itself from the similarly named sibling get_order_status (which likely returns one order's status). The intent is inferable but not crisply stated.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as get_order_status or retry_order. The agent must guess that this is a static reference/metadata lookup rather than a per-order query.

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

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

No annotations are provided, so the description carries the full burden, and it discloses almost nothing: no pagination behavior despite a size parameter with a 500 max, no note about required permissions, and no indication of what the response contains. "Optional filters" is the only behavioral hint offered.

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

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

The single sentence is short and front-loaded with no filler, which is structurally fine, but its brevity reflects under-specification rather than efficient density — the route string occupies the space where useful content should be.

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 three-parameter tool with no annotations, no output schema, and zero schema description coverage, this description is entirely inadequate. An agent cannot infer return shape, pagination, filter syntax, or how this tool relates to the many sibling list/get/upsert 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?

Schema description coverage is 0%, so the description must compensate for all three parameters (size, item_number, customer_number), and it does not. "Optional filters" gestures at the filter params but explains none of their semantics, the regex pattern on customer_number, or the default/max of size.

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 is essentially a restatement of the tool name and HTTP route ("GET /customer-product/list"), which is a tautology rather than an explanation of what a customer-product mapping is or what listing one returns. The only added information is "with optional filters," which hints at a list operation but does not distinguish it from siblings like list_products or get_customer.

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

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

There is no stated when-to-use, no mention of alternatives such as upsert_customer_product or get_customer, and no prerequisites. "Optional filters" weakly implies a retrieval use case but gives the agent nothing to decide with.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the result is a complete enumeration of public endpoints including webhooks and lists the fields returned per entry, but it says nothing about ordering, size, or whether internal/private endpoints are excluded beyond the word 'public'.

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

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

Two tight sentences: the returned content is front-loaded, then the filter options. Every clause earns its place and nothing is repeated from the structured fields.

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

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

For a one-parameter, read-only listing tool this is nearly complete: scope, payload fields, and the full tag vocabulary are all present despite the absence of an output schema. Minor gaps remain around ordering and invalid-tag behavior.

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

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

Schema description coverage is 0% and the schema defines no enum, yet the description enumerates all ten accepted tag values (health, orders, order-status, erp, rejected, customers, products, customer-products, email-watcher, webhooks) and marks the filter optional. It does not say what happens with an unrecognized tag or confirm only one tag may be supplied.

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

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

The description states a specific verb and resource ('Every public AIOTIC endpoint') and enumerates what each entry contains (method, path, summary, auth), plus the added coverage of outbound webhooks. It does not explicitly distinguish itself from the sibling get_endpoint, so it stops short of a 5.

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

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

Usage is implied by the optional tag filter, which signals this is the browsing/discovery tool. There is no explicit when-to-use guidance or exclusion relative to get_endpoint, get_schema, or get_example, so the agent must infer the routing.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses only sort order ('newest first'). It says nothing about pagination behavior, default/max page size, whether the result set can be filtered, latency, or permissions. For an unannotated listing endpoint this leaves major 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?

It is a single terse fragment with the one useful fact (newest first) front-loaded, so there is no wasted prose. However, the brevity crosses into under-specification rather than disciplined conciseness given the two undocumented parameters and many siblings.

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

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

With no annotations, no output schema, two undocumented parameters, and a crowded sibling set including get_order_status and get_order_group, the definition leaves an agent without enough to decide when to call this or how to page through results. It is far too thin for the surrounding tool surface.

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 the page or size parameters, their defaults (1 and 20), or the 200 maximum. The parameters are conventional so the harm is limited, but the description does nothing to compensate for the coverage gap.

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

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

The description identifies the resource (orders via the /order_status/list endpoint) and adds one real fact, that results are sorted newest first. But it is essentially a restatement of the tool name plus a route, with no scope, no notion of what an order record contains, and no differentiation from siblings like get_order_status or list_rejected_emails.

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

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

There is no when-to-use guidance at all: nothing says whether this should be preferred over get_order_status, list_rejected_emails, or search_customers for locating order data. The only inference an agent can make is that this is the generic paged listing.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the return contents and that results are ordered by reading sequence, which is real behavioral context for a listing tool. It says nothing about pagination, completeness guarantees, or whether the listing can change.

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

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

A single front-loaded sentence with zero filler; the scope, returned fields, and ordering are all packed into one clause without 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 no parameters, no annotations, and no output schema, the description must convey the return shape itself, and it does so concisely (section, title, summary, ordering). Remaining minor gap is any hint about list size 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 tool takes zero parameters, so there is nothing to document; the baseline of 4 applies. No parameter-level information is needed or missing.

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

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

States a specific verb (list) and resource (guide pages) and even enumerates the returned fields (section, title, one-line summary) plus ordering semantics (reading order). It does not, however, name or contrast with siblings like search_guide or get_page, so an agent must infer the distinction.

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

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

The phrase 'in reading order' implies the browsing/enumeration use case, so usage is inferable. But there is no explicit when-to-use guidance, no statement of when to prefer search_guide or get_page, and no exclusions.

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

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

With no annotations provided, the description carries the full behavioral burden and discloses nothing: no pagination semantics despite page/size parameters, no auth or rate-limit context, no statement of what is returned, and no read-only confirmation beyond what the verb GET incidentally implies.

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

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

It is short, but this is under-specification rather than conciseness; a single fragment with no front-loaded purpose statement or useful structure. Nothing wastes words, but nothing earns them either.

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 three undocumented parameters, no annotations, no output schema, and a dense sibling set of product/customer tools, the definition is far too thin for an agent to invoke it correctly or choose it over alternatives.

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 adds no parameter meaning whatsoever. Three parameters (page, size, language_code) with defaults, bounds, and a pattern are left entirely unexplained, including what language_code actually filters.

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 is a bare HTTP route string, 'GET /product/list.', which merely restates the tool name and title rather than describing the operation in agent-facing terms. It conveys no scope, filtering behavior, or distinction from the many product-related siblings such as get_product or list_customer_products.

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

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

There is no when-to-use guidance at all: nothing says when to call this instead of get_product, list_customer_products, or search_customers. The route string implies a generic listing but offers no conditions, prerequisites, or exclusions.

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

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

With no annotations provided, the description carries the full disclosure burden and fails it. The only behavioral hint is the HTTP verb GET, implying a non-destructive read; nothing is said about pagination, default status filtering, or what a 'rejected' e-mail represents.

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 text is short but that brevity is under-specification rather than conciseness. A single endpoint fragment is not a usable, front-loaded 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?

No output schema, no annotations, no parameter documentation, and no behavioral detail. For a two-parameter list tool with an enum filter, the definition is entirely inadequate.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented 'size' and 'status' parameters, and it does not. It gives no meaning for the enum values 'pending'/'overridden' or for the size limit.

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 is the bare HTTP path 'GET /rejected/list.', which merely restates the tool name and title in endpoint form. It conveys that the tool lists rejected e-mails but adds no scope, filtering, or differentiation from siblings such as reprocess_rejected_email.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance is given. The related sibling reprocess_rejected_email is never mentioned, so the agent gets no help deciding between viewing rejected e-mails and reprocessing them.

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

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

With no annotations, the description carries the full burden. It does disclose one genuinely valuable behavioral trait — that writes are gated behind an environment flag — which is real context an agent cannot get from the schema. However, it says nothing about side effects, idempotency, reversibility, or what happens to the rejected message, which is a significant gap for a mutation tool.

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

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

Two short fragments with no filler, front-loaded with the route and followed by the prerequisite. It is terse to the point of being under-specified, but nothing in it is wasted.

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

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

For a write tool with no annotations, no output schema, and an undocumented parameter, the definition is too thin. An agent still does not know what reprocessing accomplishes, whether it is idempotent or safe to repeat, or what a successful call yields.

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

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

There is one parameter and schema description coverage is 0%, so the description's path template '/rejected/{request_id}/reprocess' is the only signal that request_id identifies the rejected e-mail and is passed as a path segment. That is modest added value, but the name is largely self-describing and no format or sourcing guidance is given.

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 is essentially the tool name expressed as an HTTP route: 'POST /rejected/{request_id}/reprocess'. Combined with the title it makes the verb+resource recoverable, but the description itself does not say in words what reprocessing does, nor does it differentiate from the read sibling list_rejected_emails.

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 only guidance is a configuration prerequisite ('Requires AIOTIC_MCP_ALLOW_WRITES=true'), which is useful but is not a when-to-use rule. Nothing states when a rejected e-mail should be reprocessed, or how this differs from retry_order or re-uploading via upload_order.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that this is a write operation gated behind AIOTIC_MCP_ALLOW_WRITES, but says nothing about side effects, idempotency, whether the retry re-enters the ERP pipeline, or what happens on repeated retries of the same request_id.

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

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

Two short sentences with no padding, and the endpoint is front-loaded. It is efficient, though the write-gate sentence is the only thing beyond a bare route string, so brevity shades into under-specification.

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

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

For a mutation tool with no annotations, no output schema and an undocumented parameter, the definition is too thin: it omits state-transition semantics, error behavior for non-failed orders, and any indication of what a successful retry returns.

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

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

Schema description coverage is 0%, so the description must compensate, yet it only embeds request_id as a URL placeholder in the path template. It never explains that this identifies the original order request (e.g. from upload_order) or whether it must reference a currently-failed submission.

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 name and title ('Retry a FAILED order (write)') give a specific verb, resource and the state precondition (FAILED), and the description supplies the concrete endpoint POST /order/retry/{request_id}. It is distinguishable from siblings like upload_order or send_order_to_erp, though the description body itself never restates the purpose and does no explicit sibling differentiation.

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

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

'Requires AIOTIC_MCP_ALLOW_WRITES=true' is a real precondition, and the title implies the tool applies only to FAILED orders. However, there is no guidance on when to choose retry_order over upload_order or send_order_to_erp, nor what to do if the request is not in a failed state.

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

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

No annotations and no output schema, so the description carries the full burden. It discloses that matching is fuzzy and that the query is embedded as a path segment, but says nothing about ranking, result limits, tie-breaking, or return shape.

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

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

One compact sentence, front-loaded with the endpoint and purpose. The raw REST path restates what the tool name already conveys, but nothing else is wasted.

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

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

With no annotations, no output schema, and zero schema description coverage, the definition should explain top_k's role and the query constraints. Neither is present, so an agent cannot fully predict behavior from the definition alone.

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 both parameters. The description reveals that query is a URL path parameter and that matching is fuzzy, but it entirely omits top_k (default 5, max 50) and the query's 2–200 character 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?

States a specific verb (fuzzy search) and resource (customer records), which distinguishes it from exact-match siblings like get_customer. However it never names an alternative sibling, so differentiation is left to inference.

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

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

There is no when-to-use guidance versus get_customer or list_customer_products, and no mention of what makes a good query. The AIOTIC analogy hints at match behavior but gives no selection 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?

No annotations are supplied, so the description carries the full burden. It does disclose the return fields (page, heading, URL, snippet), which is genuinely useful, but says nothing about read-only safety, authentication, rate limits, ranking, or whether results are empty when nothing matches.

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

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

Three tight sentences with no filler, and the core purpose plus the usage trigger are both front-loaded. Every sentence earns its place.

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

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

For a small 2-parameter search tool with no output schema, the description adequately covers purpose, trigger, and return shape. It is let down by zero explanation of the parameters at 0% schema coverage, which leaves the agent guessing about query and limit 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?

Schema description coverage is 0% and there are 2 parameters (query, limit). The description mentions 'full-text search' but never explains query syntax, the min/max length constraint, or what limit defaults to and caps at. It does not compensate for the schema's documentation gap.

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

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

States a specific verb and resource ('Full-text search over the guide (sections)') and even names the return shape (page, heading, URL, snippet). It is clearly distinguishable from siblings like list_pages or get_page, though it never explicitly contrasts itself with the page-retrieval 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?

'Use before answering any AIOTIC integration question' gives a strong, actionable trigger condition, which is unusually good for a search tool. However, it offers no exclusions or alternatives (e.g., when to use get_page instead once a section is known), so it stops short of full when/when-not 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 no annotations, the description carries the full load and does disclose non-obvious traits: this is a POST that leaves the system and calls a third-party tenant ERP endpoint, and it is double-gated by an environment flag and confirm:true. It stops short of stating idempotency, error behavior, or whether a repeated call is safe.

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

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

One compact sentence: endpoint and external target first, then the two gating requirements. Nothing is padded and the critical constraint is not buried.

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 dangerous external mutation with no annotations, no output schema, and 0% parameter documentation, the description omits failure behavior, idempotency/retry semantics (notable given a retry_order sibling exists), and the expected order state. An agent can gate the call but cannot reason about consequences.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify confirm:true as a gate (the schema only shows default false) and the path template shows request_id goes in the URL, but it never explains what request_id identifies or which order state it must reference.

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

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

States a specific verb+resource ('send order to ERP') and pins the exact endpoint (POST /erp/send/{request_id}) and the external system involved (the tenant's ERP receive endpoint). It does not explicitly differentiate itself from siblings like retry_order or upload_order, which is the only thing keeping it from a 5.

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

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

It gives a hard precondition (AIOTIC_MCP_ALLOW_DANGEROUS=true plus confirm:true), which tells the agent when the call is permitted. However it never says when to choose this over retry_order or upload_order, nor what state the order must be in beforehand, so alternative routing is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the operation uses GET and requires no key, which are real behavioral facts, but it omits return semantics, rate limits, and any indication of what the health statuses mean.

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 packs in the HTTP method, both endpoint paths, the tenant scope, and the auth note.

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

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

The definition gives enough information to invoke the zero-parameter tool, and no output schema exists to explain return values. Still, with no annotations and no return detail, it leaves the agent without context about what the healthcheck or system-status responses contain.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond the empty input schema.

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

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

The description states a specific action (GET) and names the exact endpoints, /healthcheck and /system-status, scoped to the configured tenant. It is clear what the tool does, though it does not differentiate from any related sibling because no health-check sibling exists.

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

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

Usage is implied by the health-check and system-status endpoints, so an agent can infer this is for diagnostics. However, there is no explicit when-to-use guidance, no when-not-to-use condition, and no named alternative.

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

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

With no annotations, the description carries the full burden, and it does disclose a meaningful precondition (requires AIOTIC_MCP_ALLOW_WRITES=true) plus the test-tenant targeting. However it says nothing about what is created, idempotency, error behavior, or the ask/side effects beyond the raw endpoint, leaving notable gaps for a mutation tool.

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

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

A single sentence, front-loaded with the endpoint and payload, followed by scope and the required flag. Little wasted text, though it crams several ideas (endpoint, payload, scope, env requirement) into one clause chain.

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 write tool with no annotations and no output schema, the description covers the endpoint, tenant scope, and the write-enabling flag. It still omits parameter details (request_id, filename constraints) and any notion of return value or failure modes, so it is only partially complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely covers content and filename ('one text/markdown file built from the given content') and says nothing about the request_id UUID parameter or filename's txt/md pattern. Half the parameters remain opaque.

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

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

States a specific verb and resource (upload a text order) and adds the mechanism (POST /order/upload, builds one text/markdown file from content). It is clearly a write/upload operation, distinguishable from sibling read tools like list_orders or get_order_status. It stops short of naming any sibling alternative explicitly.

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 scopes intended use to 'exercising the flow against the mock/test tenant,' which is useful usage context, but it never states when to use this versus related write tools (e.g. send_order_to_erp) or any explicit exclusions. Guidance is implied rather than spelled out.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose two useful facts: this is a write (PUT) and it is blocked unless AIOTIC_MCP_ALLOW_WRITES=true — a real operational prerequisite. But it omits the core upsert semantics (does data replace the whole record or merge?), what happens to unmentioned fields, idempotency, and the response shape, which are critical for a mutation tool.

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

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

Two short sentences, front-loaded with the route and followed by the gating requirement — no filler and every clause carries information. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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 nested-object write tool with no annotations, no output schema, and zero parameter documentation, the description is far too thin. An agent cannot determine upsert merge-vs-replace behavior, error/response handling, or what the ten data fields should contain, leaving significant gaps before a safe 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 adds almost nothing. The path template does map 'number' to a path parameter, but the 'data' object with ten fields (name, city, email, vat_number, etc.) is entirely undocumented in both schema and description, so the agent gets no guidance on field meaning, requiredness, or format.

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

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

The description gives an HTTP route (PUT /customer/{number}), which combined with the name/title implies a create-or-update of a customer keyed by number. However, it never states in plain terms what the tool does or that "upsert" means create-if-absent/update-if-present, and it does not distinguish this from siblings like get_customer, search_customers, or delete_customer. The agent has to infer the purpose from HTTP verb semantics.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are named even though several siblings (upsert_customer_product, get_customer, delete_customer) overlap in domain. The only conditioning information is the env-var prerequisite, which gates execution but does not tell the agent when this tool is the right choice.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that this is a write operation (PUT) and requires an environment flag, but says nothing about idempotency, conflict handling, permissions beyond the flag, or what happens to existing mappings.

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 padding, and the endpoint is front-loaded. Every part is used, though the content is sparse by deliberate terseness rather than by waste.

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 four-parameter write tool with no annotations, no output schema, and 0% schema description coverage, the description is far too minimal. It adds the write-enable flag and path shape, but omits field semantics, write behavior, error handling, and return information.

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 all four parameters are undocumented in the schema. The description embeds two parameters in the URL path, revealing their path-parameter role, but gives no meaning for item_number or language_code and no semantic explanation of the two path parameters themselves.

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 provides the HTTP method and resource path for the customer-product mapping, and the title explicitly says 'Upsert customer item mapping (write)'. This clearly distinguishes it from sibling tools like upsert_customer or upsert_product, though the description itself never states the verb 'upsert'.

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

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

No when-to-use guidance is provided. The only condition mentioned is the environment flag AIOTIC_MCP_ALLOW_WRITES=true, which is a write prerequisite, not guidance about when this tool is appropriate versus alternatives such as upsert_customer or delete_customer_product.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the write nature (PUT) and a non-obvious runtime gate (ALLOW_WRITES=true), which adds value beyond the schema. But it omits essential mutation traits: whether an existing product is overwritten, idempotency, required permissions beyond the flag, and error behavior.

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

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

Two short, front-loaded sentences with no wasted words; the route is stated first and the gating constraint second. Brevity here reflects a thin definition rather than padding, so it is efficient without being exemplary.

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 4-parameter mutation tool with no annotations, no output schema, and 0% parameter coverage, the description supplies only an endpoint and a flag. Crucially missing are overwrite semantics, prerequisites, and any parameter explanation, so an agent cannot confidently call it or predict effects.

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, and it largely does not. The path template maps item_number and language_code to product identity, which is marginal added meaning, but it says nothing about description or remark, nor about the pattern/length constraints the schema enforces.

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

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

The description gives the HTTP route and method (PUT /product/{item_number}/{language_code}), which conveys that this writes a product keyed by item number and language. However, it never states in words that it creates-or-updates a product, and it offers no differentiation from siblings like upsert_customer_product or delete_product. Purpose is only implied via the route and the tool name.

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

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

It discloses one real precondition – AIOTIC_MCP_ALLOW_WRITES=true must be set – which is useful operational gating. But it gives no when-to-use guidance relative to alternatives (get_product, list_products, upsert_customer_product) and no exclusions. Usage is left largely to inference.

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