Aeroz

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope context (cross-channel: dashboard, MCP, email), but says nothing about ordering, staleness, or whether results are per-agent or organisation-wide, so it does not go far beyond the structured data.

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 with no filler; the resource definition is front-loaded and the usage instruction follows immediately.

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 retrieval tool with no output schema, the description covers what is returned and why to call it. Only ordering/recency semantics and result granularity are left implicit, which is a minor 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 100% — the single 'limit' parameter is already documented with its default (20) and max (60) in the schema. The description adds no syntax, ordering, or default information, so the baseline 3 applies.

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

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

The description names the resource precisely — the recent conversation between the organisation and its Aeroz agent — and specifies the channels it spans (dashboard, MCP, email). It does not explicitly name the sibling tool it complements, but 'before asking again' clearly signals it is the retrieval counterpart to ask_agent.

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

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

It gives explicit usage context: consult this to see what has already been asked and answered before asking again. That is a clear when-to-use statement, though it stops short of naming ask_agent as the alternative or stating 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?

Explains exactly why readOnlyHint=false despite being non-destructive: it refreshes onboarding state and logs the Q&A into the conversation. It also bounds side effects ('sends nothing outside Aeroz', 'changes no product, shipment or passport data') and flags declined answers and non-legal compliance signals — context annotations cannot carry.

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

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

Front-loaded with purpose and examples, then explains the grounded answer types — justified because there is no output schema. It is dense and somewhat long, but the parenthetical examples and definitions all earn their place; little could be cut without losing grounding semantics.

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?

Covers purpose, use cases, side effects, scope limits, and enumerates the `grounded` return values (records/knowledge/computed/model/declined) with where the evidence lives (chips, citations) — necessary since no output schema exists. An agent knows how to call it and how to interpret and relay the answer.

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?

Only one parameter at 100% schema coverage, so the schema already defines it and sets the 2000-char limit. The description adds that the question should be phrased in plain language as the person asked it, which is minor but real added meaning.

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 (ask) and resource (this org's dedicated Aeroz agent) and enumerates the classes of questions it answers — account state, records lookup, help topics. An agent can distinguish it from a plain data-fetch sibling like where_is or search 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?

Gives concrete example questions ('what do we still need to do', 'where is lot X') that make usage conditions vivid, and scopes reads to 'this key's read scopes'. It does not, however, say when to prefer siblings such as where_is, find_unit or search for the lookup-style questions it also claims to answer, leaving overlap 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?

Goes well beyond the annotations by disclosing the cryptographic signing model, the buyer-facing 'binding broken' failure mode, the grader_check value set and meanings, refusal conditions, and the returned verify URL. It also guards against misuse by stating what the tool does NOT do (it does not grade the card or attest pre-sealing condition).

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

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

Front-loaded with the core action, then layered with the security rationale, refusal rules, and the explicit non-claims. Length is justified by the density of distinct, decision-relevant facts; no sentence is 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 no output schema, the description correctly states the return value (public verify URL). For a 16-param mutation tool the core behavior is well covered, but the optional identity/metadata parameters remain unaddressed, leaving a modest 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?

Only 25% of the 16 parameters are described in the schema, so the description does carry weight for the required fields (uid, grade format, cert, grader) and their signing semantics. However, the 11 optional identity fields (subject, variety, category, set_name, sealed_at, images, etc.) are neither documented in the schema nor explained here.

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 (bind) and resource (an Aeroz chip to a graded collectible slab, with named graders). It is clearly distinguishable from siblings like verify_chip, graded_item, and record_provenance.

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

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

Explicitly covers when the call is refused (chip already bound, cert already bound) and names the alternative path: retire the old binding with record_provenance first. It also states the precondition for PSA cross-checking (PSA_API_TOKEN configured).

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 destructiveness, idempotency, and open-world behavior, but the description adds non-obvious behavioral context: the brief includes negative coverage gaps (which recall sources are NOT monitored) and a warning against overinterpreting empty findings. It does not explain the readOnlyHint=false annotation's implication that the call may have side effects, which is a minor gap.

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 front-loaded with the resource contents, followed by a usage directive and a critical guardrail. Every sentence earns its place, though the first sentence is long and dense; a little more structural separation could improve scannability.

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 output schema, the description fully specifies what the tool returns, including an unusual negative-coverage field. It also provides an essential interpretation warning, so an agent has everything needed to call it correctly and use its results responsibly.

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 zero parameters, there is nothing for the description to document beyond the default baseline. The description correctly focuses on what the tool returns and when to use it rather than wasting space on non-existent inputs.

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 resource (this business as Aeroz holds it) and enumerates its exact contents: product categories with mandate dates and fixed/provisional status, onboarding state, open findings, and unmonitored recall sources. It clearly distinguishes this comprehensive orientation tool from narrower siblings like list_findings or onboarding_status.

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 clear usage context: 'Use this to orient before answering anything about the account.' It also provides an important exclusionary guardrail for how to interpret the results ('Never present an empty findings list as evidence of safety without also reporting coverage_gaps'), but does not name alternative tools or specify when not to use this one.

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 readOnly, idempotent and non-destructive, and the description goes well beyond them: it discloses that counts are exact only for the units swept, that the response self-reports when it hit its cap, and that an empty findings list means 'nothing failed among the swept units' rather than compliance. That last caveat is exactly the misinterpretation risk an agent would otherwise fall into.

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

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

Front-loaded with the core action, and the capped-sweep and empty-result caveats are placed after the main statement where they matter. The four-question example sentence is long but each phrase maps to a distinct intent, so it earns its space; nothing is padded.

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

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

With no output schema, the description carries the burden of explaining return values and does so: findings list, per-finding unit counts, example units, and a cap indicator. Combined with 100% schema coverage of three optional parameters, an agent has enough to call this correctly without guessing.

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

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

Schema coverage is 100%, so pack, limit and status are already documented with defaults and a maximum in the schema. The description adds no parameter-level detail such as the effect of omitting pack or how status interacts with the sweep, so the baseline 3 applies.

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

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

The first sentence names a specific verb and resource ('Sweep this organisation's units and report which regulatory checks are failing') and states the return shape: failing checks, affected unit counts, and examples to open. It is clearly distinct from single-unit tools like trace_unit or where_is, though it never names the nearest sibling (dpp_readiness) to sharpen the boundary.

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?

Quoted trigger questions ('which of my units have a broken custody chain', 'what will not pass on 18 February') give concrete when-to-use guidance that an agent can pattern-match against a user request. There are no explicit exclusions or named alternatives, so an agent must infer that per-unit or per-finding queries belong to siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them: it states no signature is verified and no chip answer is spent, and it explains the critical null semantics ('recalled:null means UNKNOWN, never report as not recalled'). That is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the core purpose and readable as a short set of dense sentences, each carrying distinct information (return fields, null semantics, sandbox behavior). Slightly long, but nearly 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, yet the description enumerates the returned fields (known, recalled, reason, severity, date, id) and explains the null/UNKNOWN case and sandbox resolution. Nothing an agent needs to interpret results or call it correctly is missing.

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

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

Schema coverage is 100% and there is a single parameter ('uid' documented as the chip UID), so the schema carries the parameter burden. The description adds only indirect meaning (e.g. sandbox keys resolve seeded chips first), which is not a parameter-level clarification, so baseline 3 applies.

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

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

States a specific verb+resource ('check whether a specific unit is subject to an active recall') and scopes it to the register. It also explicitly disambiguates from verify_chip, so an agent can distinguish it from the sibling that checks genuineness.

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?

Explicit when-to-use trigger ('whenever a unit is about to be shipped, sold, dispensed, or installed') and an explicit alternative for a different concern ('use verify_chip for that'). Both positive and negative routing are present.

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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, yet the description adds real value: an auto-verified step will refuse the call, and self-reports that contradict platform data are rejected. This refusal semantics is not derivable from 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?

Front-loaded with the action, then conditions and rationale. Each sentence carries information, though the rationale clause ('a self-report that contradicts the platform data is worse than no report') is slightly more editorial than operational.

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 two-parameter mutation with annotations present and no output schema, the description covers who the action is on behalf of, which steps qualify, refusal behavior, and key sourcing. It does not mention permission requirements or the audit-trail outcome, but those gaps are minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine guidance by telling the agent the key value comes from onboarding_status, which the schema does not say. The note parameter's purpose is left to the schema.

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

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

States a specific verb (mark complete) and resource (manual onboarding step on behalf of the organisation), and immediately scopes it to self-reported, non-verifiable steps. This distinguishes it from the read-only siblings onboarding_status and onboarding_next_step without opening their schemas.

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

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

Gives clear conditions for use: only steps the customer owns and Aeroz cannot verify automatically, and directs the agent to obtain the key from onboarding_status. It stops short of naming an alternative tool for the opposite case (auto-verified steps), but the exclusion condition is explicit.

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

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

The annotations already declare a non-readonly, non-idempotent, non-destructive write operation. The description adds useful context beyond annotations: it references the POST /v1/products rules, states the identifier requirement for recall watch, and clarifies that the returned passport gap is a readiness signal rather than a legal determination.

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 three tight sentences with no filler. It front-loads the core action ("Register one product") and then adds only relevant constraints and return-signal caveats.

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?

This is a 10-parameter mutation with a nested object, low schema coverage, and no output schema. The description gives some return context but does not compensate for the missing parameter semantics or explain failure/duplicate behavior, leaving important gaps for correct invocation.

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

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

Schema description coverage is only 20% across 10 parameters, so the description must compensate. It mentions GTIN, NDC, and UPC in the recall-watch context, but leaves most parameters—including sku, brand, category, dpp_fields, description, and lot_numbers—without added meaning, and does not explain the nested dpp_fields 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 states a specific verb and resource: "Register one product," and references POST /v1/products for the governing rules. It implicitly distinguishes single-product registration from sibling tools like import_products, but does not explicitly name the alternative.

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 "Register one product" implies single-record creation versus batch import, and the recall-watch identifier requirement gives one usage condition. However, it does not explicitly say when to use this tool versus import_products, list_products, or other product-related siblings.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's job is to add context — and it does: it enumerates what each profile actually monitors (cold_chain MKT, high_value chip-verified custody at every handoff, etc.) and discloses the return ('the shipment id and the thresholds that will judge it'). It does not explicitly warn that repeated calls create distinct shipments despite idempotentHint=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?

The purpose is front-loaded in the first clause, followed by profile semantics and then input requirements and return value. The single dense paragraph has no filler sentences, though the profile enumeration is long enough that it slightly buries the parameter guidance mid-block.

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

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

For a 9-parameter tool with nested objects and no output schema, the description covers the highest-risk semantics (profile thresholds, coordinate format, item identifiers) and does describe the return value. It is thin only on the low-risk optional fields (carrier, planned_arrive/depart) whose schema descriptions already say ISO 8601.

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 44%, so the description has to carry weight — and it does: it explains all six profile enum values with their physical meaning, states that origin/destination require decimal-degree coordinates, and notes items may carry chip uid, GTIN, lot and serial, plus that thresholds override profile defaults. Carrier, reference, and the planned_* dates get no added meaning, leaving a modest 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 opens with a specific verb and resource — 'Register a shipment of physical items under a sensitivity profile' — and states the operational intent ('so Aeroz can watch it in transit'). That is enough to separate it from siblings like list_shipments, shipment_status, or plan_route without opening any 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 purpose statement rather than stated: an agent can infer this is the creation step before shipment_status/log_telemetry apply. However, no sibling is named, no when-not condition is given, and prerequisites (e.g., whether profiles must be inspected via shipment_profiles first) are not mentioned.

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 safety profile is known. The description adds useful behavioral context: it describes returned readiness fields, the 71 battery data points, battery-category handling, and an important legal-interpretation caveat.

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 front-loaded with the main purpose, then quickly covers return content, battery-specific behavior, and the critical caveat. Every sentence carries useful information and there is no redundant wording.

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?

Although there is no output schema, the description names the key returned fields and explains the battery-specific assessment structure. Combined with annotations that cover safety and idempotency, it provides enough information for an agent to invoke the tool correctly and interpret its output cautiously.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the battery category names and the unit_id use case for a single battery passport, but it adds little semantic detail beyond what the schema already provides.

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

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

The description states a specific verb and resource: assess readiness of a product category for an EU Digital Product Passport against the applicable delegated act. It also distinguishes the tool from sibling passport tools by explaining that it returns required, present, and missing data fields rather than passport contents or verification results.

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 for use, including battery-specific categories and the condition for passing unit_id for a single battery passport. It also includes a critical usage caveat that output is a readiness signal, not a legal compliance determination, though it does not explicitly name which sibling to use instead for compliance-style checks.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds genuinely useful behavioral context beyond that: it returns history and verdicts, and it explicitly distinguishes 'never seen' from 'seen but failed' — an output-semantics nuance the annotations cannot convey.

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

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

Three front-loaded sentences: the core action first, then the usage framing, then the important caveat about the two failure modes. Efficient overall, though the middle framing sentence is close to redundant with the opening 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 output schema, the description carries the burden of explaining returns and does so (history and verdicts), and annotations cover the safety profile. It is nearly complete for a read-only resolution tool, with the remaining gap being no guidance on how the four optional identifier parameters combine.

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 50% (uid and upi are documented; gtin and serial are not). The description maps some meaning onto them by framing 'a GTIN plus serial' as a composite alternative and 'GS1 Digital Link URI' as the upi form, but it never clarifies precedence or whether these forms are mutually exclusive. This partially compensates 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?

States a specific verb (resolve), the resource (a unit), and enumerates the accepted input forms (chip UID, GS1 Digital Link URI, GTIN+serial) plus the return content (history and verdicts). The distinction between a non-resolving identifier and a failed verification effectively separates it from verify_chip/trace_unit.

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?

'This is the tool for "what is this thing in front of me"' gives a clear situational context for use, and the failure-mode guidance tells the agent how to interpret outcomes. However, no sibling is named as an alternative, so there is no explicit when-not guidance against verify_chip or trace_unit.

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 safety profile is covered. The description adds genuine value beyond that: it warns the sample rows are fictional and not real data, and notes the response includes the row limit and the matching rule for existing products — behavioral facts the annotations don't carry.

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 dense sentence that front-loads the main payload (the columns) and then enumerates the extras. It is slightly over-stuffed with comma-separated clauses but every element earns its place.

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

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

With no output schema and no parameters, the description must explain what comes back, and it does: columns in template order, sample rows, row limit and matching rule. Only the response shape/format (e.g. a single object vs. a list) is left implicit.

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?

Zero parameters, so there is nothing for the description to disambiguate. Baseline 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 names a specific resource: the column set that import_products consumes, along with sample rows, row limit and matching rule. It distinguishes itself from the sibling import_products by describing the specification rather than the action itself, though it uses a noun phrase rather than an explicit verb like 'returns'.

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 'The columns import_products reads' implies the tool should be consulted before calling import_products, but there is no explicit when-to-use statement or exclusion. The agent must infer the workflow relationship.

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/non-destructive, yet the description adds substantial behavioral context beyond them: restricted fields are listed as withheld rather than shown, links from other resolvers are refused not fetched, and no auth is required. That is exactly the extra context the annotations do not carry.

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

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

Front-loaded with what it does, then the identifier forms, then the critical disambiguation from verify_chip. Every sentence carries information, though the run is slightly long and could be tightened.

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

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

With no output schema, the description compensates by enumerating return contents (signed fields, version and date, recall status, item links) and by covering auth, refusal, and sandbox caveats. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (date, dpp_id, version, digital_link) are already documented, including the dpp_id/date/version pairing rules. The description confirms the accepted identifier forms but adds little syntax beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource ('Read the PUBLIC view of a published Digital Product Passport') plus the two accepted identifiers. It explicitly distinguishes itself from the sibling verifier ('use verify_chip... for that') and from verify_passport_credential territory, so an agent can select it 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?

Gives explicit when-to-use and when-not-to-use guidance: it reads the record only and does NOT prove the physical item, with a named alternative (verify_chip with a fresh chip tap). It also states the no-API-key condition and that sandbox org passports are not public in production.

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, closed-world and non-destructive, so safety is covered. The description adds genuine domain behavior: the exact bucket taxonomy, the non-obvious rule that a recalled tap counts even when unverified, and the invariant that buckets always sum to total. It omits anything about retention, latency or auth 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?

Front-loaded with the core purpose in the first sentence; the second sentence is a long but information-dense definition of the buckets. Every clause carries meaning, though the bucket enumeration is heavy enough that it could be tightened.

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

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

There is no output schema, so the description must describe what comes back; it does so by enumerating the outcome buckets and asserting they sum to total. It still leaves the response shape (field names, whether counts are nested by date, totals placement) unspecified, which for a reporting tool with no output schema is a modest 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 100% and the single 'days' parameter already documents default 30 and max 365, so the schema does the heavy lifting. The description only refers to a 'recent period' in prose and adds no format or edge-case detail beyond the schema, making the baseline of 3 appropriate.

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

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

States a specific verb (return) and resource (this organisation's verification volume and outcome breakdown) with explicit scope (organisation, recent period). It is clearly distinguishable from siblings like verify_chip or list_findings, which act on individual units rather than aggregate reporting.

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

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

Explicitly says what it is for: reporting on scan volume, authentication failure rates, and trend, which is concrete context for selection. It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior context by enumerating what the record contains (grader's own record match, tap verification count, provenance chain events) and by instructing the agent to 'report what this proves AND what it does not'. It omits error/not-found behavior for an unknown item_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?

Front-loaded with the subject, then usage examples, then a short directive. The field enumeration is long but each item is informative; nothing is gratuitous 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 single-parameter read tool with no output schema, the description does well: it sketches the returned record and its provenance chain without needing to define a return shape. The one real gap is that item_id and the failure mode for a bad ID are left unaddressed.

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 parameter item_id is unexplained in both the schema and the description; the agent gets no hint about format, origin, or how it relates to other identifiers in the domain. With low coverage the description was expected to compensate and does not.

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 framed as a payload definition ('A graded item as Aeroz holds it: grader, cert, grade...') rather than a stated action; it never says plainly that this fetches a single graded item by ID. The usage examples imply a lookup, but the sibling list_graded_items is never distinguished from this tool, so the agent must infer the single-item scope.

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?

Three concrete trigger questions ('is this slab the one that was sealed', 'where has it been', 'has anyone tried to pass off a copy') give clear context for when to reach for this tool. It stops short of naming alternatives or exclusions, e.g. when to use list_graded_items or trace_unit instead.

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 (readOnlyHint=false, idempotentHint=true), the description discloses the 5,000-row cap, all-or-nothing semantics ('writes nothing while any row has a problem'), the per-row outcome vocabulary (create/update/unchanged/conflict), and that dry_run writes nothing. That is exactly the operational context an agent needs before a bulk mutation.

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

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

Four sentences, front-loaded with purpose, then limits, then recommended workflow, then failure semantics and return shape. No filler and no repetition of schema text.

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 exists, yet the description provides the return vocabulary the agent needs to interpret results, plus size limits and atomicity behavior. Nothing essential for a correct two-parameter bulk call is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by explaining that each row carries the fields of create_product and by spelling out the intended dry_run-first workflow rather than just its type. It does not enumerate row-level required fields, which keeps it below 5.

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 with batch scope ('Add or update many products at once') and makes the upsert nature explicit, which distinguishes it from the singular create_product sibling. An agent can tell immediately what this does and that it is not a single-record call.

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

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

Gives a concrete workflow rule — 'Send `dry_run: true` first' — and defines the failure/validation protocol. It does not name siblings such as create_product, get_import_template_columns or list_products as alternatives for other cases, so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the enabled/available scoping dimension but says nothing about return shape, ordering, or pagination; on par with the calibration example where annotations carry the safety load.

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, zero filler, and the resource plus scope are front-loaded before the usage hint. 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 no-parameter, read-only listing tool with no output schema, the description supplies enough: what it lists (agents available to the org) and which subset matters (enabled). Only the return format is unspecified, which is minor here.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The 4 baseline applies and no parameter detail 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?

States a specific verb and resource ('List the Aeroz compliance agents') and adds meaningful scope: available to this organisation and currently enabled. It does not explicitly distinguish itself from related siblings like ask_agent or agent_conversation, but its purpose is unambiguous.

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

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

Gives two concrete use cases ('explain monitoring coverage' or 'find an agent worth enabling'), which is clear context for when to reach for it. It stops short of naming alternatives or when-not-to-use conditions, so it doesn't reach the top tier.

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

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

Annotations already declare this a read-only, idempotent, closed-world listing, so the safety profile is covered. The description adds genuinely non-obvious domain behavior — the four tier vocabularies and their operational meaning (live vs credentials vs bridge vs guided) — plus an explicit constraint on how results may be characterized to users ('do not describe a guided connector as automatic').

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, front-loaded with what the resource is before the tier glossary. The backticked tier vocabulary is dense but each term earns its place since it defines returned semantics; only the slightly awkward '`tier_means` in words' phrasing adds friction.

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 carries the burden of explaining returned content — and it does, by defining the `tier` field and its four possible values. What remains uncovered is whether the list is paginated or includes connector metadata beyond tier, a minor gap for a zero-parameter catalog 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 takes zero parameters, so the baseline of 4 applies. The description correctly implies an unfiltered full listing and adds nothing misleading about inputs.

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

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

The description names the concrete resource — external systems Aeroz can connect to — and enumerates the categories (WMS, ERP, commerce, EPCIS), which is enough to know this is the connector catalog. It does not, however, differentiate itself from the near-identical sibling `list_integrations`, leaving an agent to guess which catalog to open.

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

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

Usage is only implied: the description explains what tiers mean, which signals 'use this to interpret or explain connector options to a user'. There is no explicit when-to-use statement, no exclusion, and no mention of `list_integrations` as the alternative, so the agent must infer 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds genuinely new context: the findings are agent-generated, org-scoped, and span a specific set of detection categories. It stops short of any ordering, acknowledgment-state, or return-shape detail.

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, zero waste, and the core scope statement is front-loaded ahead of the routing hint. Every clause earns its place by naming a distinct detection category.

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, fully-annotated, zero-required-param read tool with complete schema coverage and no output schema, the description covers purpose, scope and trigger adequately. Minor gap: nothing about ordering or default result count, though the schema supplies the default.

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

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

Schema description coverage is 100% — limit (default 25, max 200) and the severity enum are fully documented in the schema with sensible defaults. The description adds nothing about filtering or paging semantics, so the baseline 3 applies.

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

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

States a specific verb (List) plus the resource (findings) and its origin (raised by Aeroz compliance agents watching this organisation). It then enumerates the concrete finding categories — recall hits, DPP gaps, regulatory changes, dwell anomalies, clone detections — which an agent can distinguish from siblings like check_recall or dpp_readiness that each cover only one slice.

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 closing sentence gives a clear situational trigger ('what needs my attention'), which frames when to reach for this aggregate list rather than a point-check tool. However, it names no alternatives and gives no exclusions, so the routing decision against check_recall/dpp_readiness 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the organisation-scoping constraint, which corroborates openWorldHint=false, but says nothing about ordering, pagination behavior, or what a default (unfiltered) call returns.

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

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

A single sentence with zero filler, front-loading the resource and its scope before the optional filter. 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?

For a two-parameter read-only list tool with no output schema, the definition is minimally serviceable: it explains the filter but not the `limit` semantics, the default result set size, or the return shape. Adequate but with clear gaps an agent would need to discover by trial.

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 neither parameter has an enum, so the description carries real weight here: it enumerates the valid status values (sealed | active | flagged | retired) that the schema omits entirely. However, the `limit` parameter is never mentioned, leaving half the inputs unexplained.

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 a precisely scoped resource (this organisation's chip-bound graded items), which separates it from the singular detail tool `graded_item` and the mutating `bind_graded_item`. It stops short of explicitly naming siblings, so an agent must infer the relationship rather than being told 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?

The only usage hint is 'optionally by status', which is really a parameter note rather than routing guidance. There is no statement of when to reach for this versus `graded_item`, `list_sandbox_chips`, or `find_unit`, and 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?

Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to restate those safety traits. It adds valuable domain context by explaining that only `connected` is proven and that `unverified` means stored but not yet proven, which directly affects how an agent should interpret results.

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 both carry useful information: the resource identity first, then the critical status semantics. The opening phrase is slightly fragmentary, but there is no filler or repetition.

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

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

With no output schema, the description must explain what comes back, and it does so at the level of status and status meaning. It could say more about the integration object shape or ordering, but for a simple parameterless list tool it is largely 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?

The tool has zero parameters, so there are no parameter semantics to document. The baseline for a parameterless tool is 4, and the description appropriately avoids inventing parameter guidance.

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 as 'This company's connected systems' and notes that each includes `status` and `status_means`, so the agent knows this is a list-style read of integrations. It does not differentiate itself from nearby siblings such as `list_connectors` or `test_integration`, which keeps it 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?

There is no explicit guidance on when to use this tool versus alternatives like `list_connectors` or `test_integration`. The listing use case is implied by the resource description, but no exclusions or routing guidance 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 declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: archived products are silently excluded, and an empty result means 'no products registered' rather than 'no recalls found' — a meaningful trap for an agent. It adds no ordering, pagination or rate-limit context, so not a 5.

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

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

Two short sentences, no padding, with the scope constraint front-loaded. The parenthetical exclusion is efficient; the empty-list caveat is slightly tangential to the tool's stated purpose but earns its place as a misinterpretation guard.

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 list tool with no output schema, the description covers scope, exclusions and the empty-result edge case. Ordering of returned products and pagination behavior beyond 'limit' are unaddressed, which keeps it from a 5.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully documented in-schema with range and default. The description adds no additional meaning about limit, so the baseline 3 applies.

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

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

The description names the resource and its scope precisely: 'this company's registered products' with 'archived ones left out'. Combined with the name/title the verb is unambiguous. It does not, however, differentiate from siblings like import_products or create_product, 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 (call this to see the product catalogue that recall matching operates on), but there is no explicit when-to-use/when-not guidance and no alternatives named. The 'empty list' note clarifies interpretation rather than steering tool selection.

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, idempotent, non-destructive behavior, so the description sensibly spends its words on non-obvious data semantics instead: seeds are per-organisation, one per scenario, and the signature_mismatch entry carries a deliberately WRONG signature while not_found is a UID absent from the register. That prevents an agent from misreading intentional test fixtures as errors. It stops short of describing return shape beyond the scenario list.

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, zero waste: the first defines the output and enumerates the scenarios, the second carries the sandbox constraint and the use case. The most important qualifier ('Sandbox only') is placed where it cannot be missed.

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 and no output schema, the description carries the full explanatory burden and does so: it enumerates every scenario returned and clarifies the intent of the anomalous entries. An agent has everything needed to call it and interpret the result.

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 schema cannot carry semantic load and the baseline is 4. The description does add meaning to what is returned (UID plus signature, one entry per named scenario), which is the only semantic detail available for a no-arg 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?

States a specific verb and resource ('List the seeded sandbox chips') plus the exact payload returned: UID and signature to pass to verify_chip. It names the four scenarios returned, so an agent can distinguish this from production-oriented siblings like verify_chip or list_shipments 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?

Explicitly scopes usage: 'Sandbox only — use when building or testing an integration before physical chips ship.' It also routes the agent downstream by naming verify_chip as the consumer of the returned UID/signature. When-to-use and the boundary against real-chip flows are both 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds only the organisational scoping ('this organisation's'), and says nothing about result size, pagination, or ordering — modest added value above 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?

A single sentence with the filter scope front-loaded and no filler. Every clause carries information.

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

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

For a simple read-only list tool with no output schema needed, the description plus annotations cover the essentials. The remaining gap is the undocumented 'limit' semantics (page size? max results?) for an unannotated parameter.

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 supply the accepted status values (planned | in_transit | delivered | exception | cancelled), which the schema lacks entirely, but the 'limit' parameter is left completely unexplained in both schema and description.

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+resource: 'List this organisation's shipments', with the scope of the collection made explicit. It does not, however, distinguish itself against adjacent siblings such as shipment_status or shipment_profiles, leaving the agent to infer which of the related tools fits.

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?

'Optionally by status' implies filtering behavior, so usage is inferable for the primary case. There is no when-to-use versus when-not guidance and no mention of how this differs from shipment_status or shipment_profiles.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description nonetheless adds real behavioral context beyond them: newest-first ordering, that each row includes every attempt and the receiver's response, and that a pending delivery with next_attempt_at is being retried rather than lost. It also discloses the required webhooks:read scope, an auth detail no annotation covers.

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

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

Three short sentences, front-loaded with the resource and ordering, then the retry semantics, then the scope requirement. Every clause carries information an agent needs; nothing is repeated from the schema.

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

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

With no output schema, the description usefully sketches the return payload (attempts and receiver answers) and explains the ambiguous pending state, plus the auth requirement. It omits any pagination or result-cap behavior beyond the schema's limit field, a minor gap for a read-only list.

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

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

Schema coverage is 100%, so limit, status, and endpoint_id are fully documented in the schema and the baseline is 3. The description adds only a semantic gloss on the ' pending' status meaning; it says nothing about the filters, ranges, or defaults that would deepen parameter understanding.

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 (recent webhook deliveries), the ordering (newest first), and the return shape (every attempt plus receiver's answer), which clearly separates it from list_webhook_events and list_webhook_endpoints. It never names a sibling explicitly, but the resource is specific enough for correct selection.

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

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

Usage is only implied ('Recent webhook deliveries'), with no when-to-use statement, no exclusion criteria, and no pointer to the sibling list_webhook_events or list_webhook_endpoints tools. The note that pending deliveries carry next_attempt_at is helpful context but is not guidance on selecting this 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not carrying that burden. It adds genuine behavioral detail beyond them: query strings are stripped from addresses, signing secrets are never returned, and the `webhooks:read` scope is required — all material for an agent deciding whether the output is safe to surface.

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, each earning its place: the first defines the payload field by field, the second states the security guarantee and the auth requirement. The most important content is front-loaded and nothing is repeated from structured fields.

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

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

With no input parameters and no output schema, the description must characterize the returned data — and it does precisely (address, events, health), plus redaction behavior and scope. An agent has everything needed to call it and to know what it will get back.

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 schema imposes nothing to misinterpret; the baseline for no-parameter tools applies. The description correctly implies a no-argument, all-endpoints listing with no filtering options.

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 resource (the company's webhook endpoints) and enumerates exactly what each entry contains: address with query string hidden, subscribed events, and health in words. It is clearly a listing read, distinguishable in substance from list_webhook_deliveries and list_webhook_events, though it never names those siblings to route the agent 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?

Usage is only implied: an agent infers it should call this when it wants to inspect configured endpoints. The one explicit condition is the `webhooks:read` scope requirement, which is a prerequisite rather than when/when-not guidance. No alternative tool (e.g. list_webhook_deliveries, list_webhook_events) is mentioned.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — which it does by disclosing that example payloads contain fictional sample data, and that signing and retry-schedule documentation is bundled in. That is genuinely useful behavioural context an agent would otherwise not have. It stops short of describing the response shape or ordering, keeping it below 5.

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

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

A single dense sentence with no filler, and the most decision-relevant caveat (example payloads are fictional, not real data) is included early. It loses a point only for being a fragment rather than a front-loaded statement of what the tool returns.

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, zero-parameter reference tool that already carries full annotations, the description covers what content comes back (event list, descriptions, sample payloads, signing, retry schedule). No output schema exists, but the description effectively enumerates the return contents, so nothing critical is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description also correctly implies a no-argument catalogue 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 identifies the resource as the full catalogue of webhook event types Aeroz can emit, plus signing and retry documentation, which usefully clarifies this is a static reference rather than a log of past deliveries. However, it is written as a noun-phrase fragment with no verb ('returns'/'lists'), and it does not name or distinguish itself from close siblings like list_webhook_deliveries or list_webhook_endpoints.

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

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

There is no explicit statement of when to call this tool or when to prefer list_webhook_deliveries/list_webhook_endpoints instead. The agent must infer usage purely from the content inventory, and the near-identical sibling names make that inference risky.

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

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

Annotations only say readOnlyHint=false and idempotentHint=false; the description goes far beyond, disclosing side effects (state transition to in_transit), refusal/ignore behavior with counting (>500 readings, future readings, duplicates), acceptance windows, and the per-logger judging model. This is exactly the behavioral context the annotations cannot carry.

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 purpose is front-loaded and every sentence conveys distinct rules (limits, transitions, windows, return shape). It is a dense single paragraph, which is information-efficient though the middle sentences are heavily packed.

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 ingest tool with no output schema, the description supplies the return shape (assessment, worst logger, temp.by_source, unobserved minutes), the side effects, and the validation rules. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 0%, so the description carries the burden, and it compensates well by mapping the reading fields (position, temp, humidity, shock, tilt, light, battery) and stating the 500-item limit on the readings array. It is slightly less explicit about shipment_id's role, keeping it from a 5.

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

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

The description opens with a specific verb and resource ('Record sensor readings for a shipment') and enumerates the reading types covered. It is clearly distinguishable from sibling write tools like record_custody and record_provenance by naming its own domain (sensor telemetry).

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 strong conditional context: a `planned` shipment transitions to `in_transit` on first reading, post-`delivered` loggers are accepted only within the journey window, and cancelled shipments accept none. It doesn't name an alternative sibling or an explicit 'use X instead' condition, so it stops 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?

Goes well beyond the annotations by disclosing a provenance/trust model — `computed` vs `sourced` vs `drafted` — and two behavioural directives (cite the confidence you rely on; never present a `drafted` block as settled). These are exactly the kind of usage constraints annotations cannot express. The one gap is that readOnlyHint=false is never reconciled with what reads as a pure retrieval tool, so an agent cannot tell whether calling it has side effects.

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

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

Four sentences, front-loaded with the purpose before the block inventory, and every sentence carries information: contents, confidence semantics, and the drafting caveat. The block enumeration is long but each item is load-bearing rather than 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 no output schema, the description carries the full burden and does so by describing the return shape block-by-block plus the confidence field. Remaining gaps are minor: block values packet, profile, regimes, contacts and carrier are never explained, and side-effect behaviour is unaddressed.

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 enum values are already listed in the schema, so baseline is 3. The description adds real meaning to most values — 'calendar' means only ADOPTED dates, 'passport' means per-product scaffolds showing missing fields, 'identifiers' is an audit, 'gs1' is a route — usefully expanding seven of the twelve enum members.

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 with clear scope: "Return everything the Aeroz agent has built for this organisation," then enumerates seven concrete content blocks (calendar, passport scaffold, identifier audit, GS1 route, coverage, integration, audit scope). An agent can tell this is the aggregate/organisation-level view rather than a single-purpose checker, though no sibling tool is named 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?

"Use this to answer almost any question about what this business needs to do" gives a clear, actionable when-to-use rule that routes the agent here over the narrower sibling checks. It does not state when NOT to use it (e.g. for a single shipment or unit lookup) nor name alternatives, so it stops 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 the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond that: the result is scoped to exactly one action plus completion instructions, which matters because there is no output schema to convey the return shape. It does not explain the readOnlyHint=false flag on what reads like an advisory lookup, a minor unexplained note.

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 with zero waste: the first front-loads what the tool returns, the second front-loads the usage condition. 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?

For a zero-parameter tool with no output schema, the description covers both the trigger and the return content, which is the essential information. It stops short of noting edge cases such as what happens when onboarding is already complete, which would round out the definition.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies a parameterless call derived from onboarding state, and adds no misleading input expectations.

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: it returns 'the single most important next action and how to complete it.' The phrase 'does not want the whole checklist' implicitly distinguishes it from onboarding_status and complete_onboarding_step, though it never names those siblings, so the differentiation is inferred rather than explicit.

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

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

Gives a clear trigger condition: 'Use when the user asks what to do next and does not want the whole checklist.' This covers when to use it and implicitly when to prefer the fuller checklist view, but it does not name the alternative tool the agent should call instead.

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 cover safety (destructiveHint=false, idempotentHint=true), so the bar is lower, and the description still adds genuinely useful interpretive behaviour: side="aeroz" steps are Aeroz's obligation and must be framed as such. It also compensates for the absent output schema by listing the returned fields. It does not reconcile the surprising readOnlyHint=false for what reads like a pure reporting call, so it is not fully transparent about whether invoking it mutates anything.

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

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

Front-loaded with the payload contents before usage and caveat, and each of the three sentences carries distinct information with no filler. The quoted question list is slightly padded but does buy real usage signal.

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 no-parameter tool with no output schema, the description covers both the return contents and the intended questions well, which is the main completeness burden here. Missing only marginal items: any note on freshness/caching or why the annotation flags it as non-read-only.

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 per rubric the baseline is 4; there is no argument syntax the description needs to add. Schema coverage is 100% and empty, requiring no compensation.

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 ('Report where this organisation stands') and resource (Aeroz onboarding), then enumerates exactly what is returned: stage, percentage complete, health, next action, and open steps with owner. It does not, however, differentiate itself from the sibling 'onboarding_next_step' or 'complete_onboarding_step', which is a real overlap given it also returns 'the single next action'.

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

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

Gives concrete consumption contexts via the quoted operator questions ('what do we still need to do', 'why are we not live yet', 'what is Aeroz waiting on'), which tells the agent when this beats a generic status lookup. It stops short of naming an alternative tool or stating when NOT to use it (e.g. versus onboarding_next_step).

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

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

Annotations only declare non-read-only, non-idempotent, open-world; the description goes well beyond by explaining the scoring model (traffic duration/delay, heat/cold against the lane ceiling, rain/snow/gusts), that lower is better, that scores are only comparable within one computation, that the best route is marked chosen, and that it degrades to a time-only ranking when routing or weather data 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?

Three sentences, front-loaded with the core action and followed by scoring semantics and the degradation caveat. Dense but nearly every clause carries information; the 'relay that' aside is the only slightly stray 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?

For a complex, output-less tool the description covers what is computed, how it is scored, comparability limits, and failure/degradation behavior. It does not describe the shape of the returned route list or how many routes are ranked, a modest gap given no 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?

Schema coverage is 50%: depart_at is documented as ISO 8601 with a default, shipment_id is bare. The description re-states 'at a departure time' and 'for a shipment' but adds no format, default, or identity semantics beyond the schema, so it only partially compensates for the uncovered 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?

States a specific verb pair and resource: 'Compute and rank routes for a shipment at a departure time.' Route ranking is not offered by any sibling (create_shipment, shipment_status, list_shipments, trace_unit), so the agent can place it immediately.

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 rather than stated: the agent learns the tool scores a shipment's route, but there is no explicit 'use this when...' or 'do not use when...'. The instruction to relay degraded (time-only / straight-line) results is useful operational guidance but is about output handling, not tool selection.

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

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

Annotations only establish write/non-destructive/non-idempotent; the description goes well beyond by disclosing consequences (a handoff without a verified chip on a high_value lane raises a finding), the uid_not_in_shipment verify_result distinction, and the terminal-state rule. This is exactly the side-effect detail an agent needs before a write.

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 dense paragraph, front-loaded with the action and the kind list before the behavioral rules. Every clause carries information, though the verification-result discussion is packed tightly enough to warrant a re-read.

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 no-output-schema write tool with 10 params, the description covers behavior, state transitions, and failure modes well. The remaining gap is that several input fields (location, actor, occurred_at, lat/lng, note) are never explained.

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% across 10 parameters. The description adds real meaning for `kind`, `uid`, and `signature`, but says nothing about lat, lng, actor, location, occurred_at, or note, and the verify_result/chip_verify_result terms describe outputs, not params. Partial compensation only.

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 ('Record a custody event on a shipment') and enumerates the exact event kinds, which cleanly separates it from siblings like log_telemetry, verify_chip, and create_shipment. An agent can tell what this tool does 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?

Gives clear when-to-use context for each kind and an explicit exclusion: delivered/cancelled shipments accept only `note` events, and pickup must precede delivered. It does not name sibling tools (verify_chip, log_telemetry) as alternatives, but the state-machine conditions leave little to inference.

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

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

Annotations only declare the mutation/idempotency profile; the description adds real behavior — events are append-only, public events surface on the buyer's tap page, and retired ends the binding (chip stops vouching, cert freed). This is meaningful context beyond the structured hints. It does not contradict destructiveHint=false, since retired changes binding state rather than deleting data.

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

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

Front-loaded with verb and resource, then event-specific constraints. Dense but every clause carries information; no filler.

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

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

For a 7-parameter mutation with no output schema, the behavioral picture is good but several parameters (actor, public, location) remain semantically unexplained in either the schema or the 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?

Schema coverage is only 14% (just occurred_at), so the description must compensate. It explains 'kind' values and the meaning/requirement of 'note', but leaves 'actor', 'public', and 'location' undocumented, so compensation is partial.

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

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

The description opens with a specific verb and resource ('Append an event to a graded item's chain') and enumerates the exact event kinds, so the operation is unambiguous. It does not name or contrast with the similar-looking sibling record_custody, which keeps it from a full 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 conditional guidance per event kind ('flagged' needs a note, 'retired' ends the binding, a retired item accepts only 'note' events), which tells the agent when each mode applies. It stops short of naming an alternative tool or an explicit when-not-to-use-this rule.

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/non-destructive, and the description adds substantial extra behavior: identifier normalization and exact-match-first ordering surfaced via `match: identifier`, per-area read scopes with unreadable areas reported in `skipped`, and `href` pointing to the dashboard screen each hit opens. No contradictions with the read-only annotation.

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

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

Front-loads the core purpose and the dashboard analogy before the taxonomy, and every clause carries information rather than filler. The long parenthetical identifier lists are dense but each one tells the agent something it would otherwise have to guess at.

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 exists, so the description must explain return shape — and it does, covering `match: identifier`, `skipped` for scope gaps, and `href` per hit. For a two-parameter federated search tool that is everything an agent needs to call it and interpret the response 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 coverage is 100%, so q and limit are already documented, and the description adds real semantics on top — it specifies what q accepts (GTIN, NDC, GLN, lot, chip ID, GS1 Digital Link, element string, EPC URN) and that such input is parsed. The 300-character cap and the limit default/max remain schema-only, which is fine given full 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?

Opens with a specific verb and resource ("Search this company's records") and then enumerates exactly which entity types are covered, including the identifier fields matched in each. The dashboard-search-bar analogy plus the explicit list makes it immediately distinguishable from narrow siblings like list_products or find_unit.

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

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

Gives a concrete usage rule ("Paste an identifier as-is") with the formats that trigger parsing, and explicitly routes question-answering to ask_agent. It also supplies an interpretation rule — don't read an empty group as "none" when the area appears in `skipped` — which is exactly the kind of when/when-not guidance an agent needs.

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

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

Adds substantial context beyond annotations: the payload is a signed `ping`, the call is a real outbound request with no retry, the response includes HTTP status and body, and it requires the `webhooks:write` scope. This aligns with openWorldHint=true and idempotentHint=false rather than 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?

Two tight sentences: behavior and return value first, then the safety/authorization caveats. No filler.

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

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

Even without an output schema, the description explains what is returned (HTTP status and body) and the risk profile (live request, no retry, required scope). An agent has everything needed to call it correctly.

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

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

Only one parameter and the schema documents it fully (whe_... id from list_webhook_endpoints), so the description adds nothing on parameter semantics. Baseline 3 for full 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?

States a specific verb (send a signed ping) and resource (one webhook endpoint) plus the immediate effect (return the receiver's answer). Clearly distinguishable from siblings like list_webhook_endpoints and list_webhook_deliveries.

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?

Makes the key condition explicit — it sends a real request to the customer's address right now and is not retried — which tells the agent this is a one-shot live probe, not a queued job. It does not explicitly contrast with test_integration or say when not to use it, so it falls short of 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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful content detail (exact thresholds, provider-config status), but with no output schema it stops short of describing the shape of what is 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 tightly packed sentence with no filler, front-loaded on the primary resource. It is dense but every clause (profiles, thresholds, provider config) maps to real returned 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 no-param, read-only reference tool with no output schema, the description communicates the three categories of data returned, which is enough for correct invocation. It could be marginally richer about return formatting, but nothing needed to call it 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?

The tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to disambiguate, and it correctly implies a no-argument configuration read.

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 resource set — the sensitivity profiles, their thresholds, and provider configuration status — so an agent knows this is a configuration/reference lookup. It does not explicitly contrast with siblings like shipment_status or create_shipment, but the returned content is unambiguous.

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

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

There is no 'use when' or 'use instead of' guidance. The description never states when an agent should call this versus shipment_status or plan_route, leaving the selection entirely to inference from the resource name.

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 the safe read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds genuine domain behavior on top: an open excursion on a cold-chain lane implies the load must be quarantined pending QA, and it instructs the agent to say so. That is actionable semantics the annotations cannot convey. It does not, however, describe response size, pagination, or what happens when the shipment_id is unknown.

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

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

Front-loaded with the payload enumeration, then use cases, then the quarantine rule — a sensible order. The field list is dense and slightly overstuffed, but each item corresponds to real returned data, so almost every clause earns its place.

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

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

With no output schema and no annotation depth beyond safety hints, the description compensates by enumerating the return contents in detail and flagging the one decision-relevant derived state (an open excursion). For a single-parameter read tool, an agent has everything it needs to call it and interpret the result.

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 the single required shipment_id, so the description carries the full burden of explaining the parameter, and it does not: it never states the ID format or where an agent obtains one (e.g. from list_shipments). 'One shipment' only weakly implies the parameter, adding no usable detail over the bare schema field.

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 retrieval verb-and-resource pair ('Everything Aeroz holds about one shipment') and then enumerates the exact payload: profile/thresholds, status, items, custody events with chip verification, telemetry assessment, ranked routes, and open findings. This is far more specific than the title or schema, and it clearly distinguishes the tool from siblings like list_shipments (plural) or trace_unit.

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 concrete trigger phrases ('where is it', 'is the cold chain intact', 'was it ever opened') that map directly onto the returned fields, so an agent knows when to reach for it. It stops short of naming alternatives such as list_shipments for enumeration or trace_unit for a single unit, so no explicit when-not guidance is offered.

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 cover mutation (readOnlyHint=false), idempotency, openness, and non-destructiveness. The description adds meaningful context beyond that: it discloses the status side effect ('Changes its status to what the test proved'), the return content including the remote server's error text, and the scope limitation ('Pulls no data'). It could still say more about auth requirements or failure semantics, but it is well above the annotation baseline.

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

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

Three short sentences, front-loaded with the core action, and every sentence contributes distinct information (return content, side effect, scope). There is no repetition 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 low-complexity tool with a single documented parameter and rich annotations, the description covers the return value including error text, the status mutation, and the no-data-pull scope. It is nearly complete; only a note on failure handling or permissions would push it to a 5.

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

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

There is only one parameter and the schema description coverage is 100% – the schema itself explains the integration_id format (int_...) and points to list_integrations as the source. The description adds no parameter detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Test one connected system now' clearly identifies a single-integration connectivity test. It implicitly distinguishes itself from list_integrations by operating on one integration and by testing rather than listing, but it never names the sibling, so it stops short of a 5.

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

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

The word 'now' signals immediate execution and 'Pulls no data' hints that this is a verification step rather than a data fetch. However, there is no explicit guidance on when to prefer this over list_integrations or other connector tools, nor any stated 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 readOnly/idempotent/non-destructive/closed-world, so the description focuses on what matters: failing checks cite the enforced clause, and the response itself carries a disclaimer that verdicts are readiness signals, not legal determinations. That interpretive framing is genuine value beyond annotations, though nothing is said about response size, latency, or behavior for unknown unit ids.

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

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

Front-loaded with what the tool returns, then the questions it answers, then the caveat — a sensible ordering. The closing disclaimer is slightly redundant ("verdicts are readiness signals... and the response says so" followed by "Never report one as confirmation"), but the repetition is defensible for a legally loaded output.

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

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

With no output schema, the description carries the burden of explaining returns, and it does: custody hops, tamper status, regulation verdicts, and clause citations for failures. Only minor gaps remain — nothing about error behavior or result volume for a potentially long append-only log.

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

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

Schema coverage is 100%, so both unit_id and pack are already documented, including the note to use find_unit when only a scan is available. The description only loosely gestures at pack via "what each regulation makes of it" and adds no syntax or defaulting detail beyond the schema, so baseline 3 applies.

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

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

States a specific resource and scope: the full custody history of one serialized unit, its tamper check, and per-regulation verdicts. This clearly separates it from siblings like where_is (point location), chain_readiness (aggregate), and find_unit (lookup), so an agent can pick it 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?

Gives concrete triggering questions ("where has this been", "who handled it", "is its record trustworthy", "does it pass DSCSA / EU passport") that map directly to use cases. It does not name exclusions or alternatives — notably where_is for a quick current location — so the boundary with that sibling 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 readOnlyHint=false and idempotentHint=false already in annotations, the description explains *why*: each call records the tap and consumes the chip's one-time answer. It then goes well beyond annotations, decoding proof 'presence' vs 'identity', the meaning of verified:false/no_signature/signature_unchecked, and sandbox key behavior. This is unusually rich disclosure for a mutation-flagged verify 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?

It is dense and long, but front-loaded with the core purpose and every clause carries load (exceptions, sandbox behavior, spend semantics). A few output-decoding details could be trimmed, but nothing is 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 no output schema, the description takes on the burden of explaining return semantics (proof, proves, verified, reason) and does so thoroughly, including the subtle no_signature vs signature_unchecked distinction and sandbox fixture modes. Complete for a complex verification tool.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the description's baseline is 3. The description adds real semantic value on top, clarifying that `signature` proves identity not presence while picc_data+cmac prove presence, and that uid is optional when SUN params or tap_url carry it.

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

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

States a specific verb and resource ('Verify a physical item by its Aeroz chip') and immediately distinguishes it from record-based tools: 'a database record proves a record exists, not that the object in front of you is the one it describes.' An agent can separate this from find_unit, trace_unit, and verify_passport_credential 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?

Gives explicit when-to-use context ('Use this before trusting any claim about a physical unit') and an operational constraint ('Each call records the tap and spends the chip's one-time answer, so pass each SUN tap once'). It stops short of naming sibling alternatives by name, so it earns a strong 4 rather than 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 readOnly/idempotent annotations, it discloses the exact return contract (valid:true with issuer, product id, passportVersion, validFrom; valid:false with reason strings such as 'revoked by the issuer'), the precise semantics of a valid result, the important limitation that validity does not imply latest version, and that no API key is required. These are exactly the behavioral facts annotations cannot express.

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 definition is front-loaded with the action and result shape, and the caveat about version staleness plus the no-API-key note are placed where they matter. It is somewhat long and repeats 'Aeroz' several times, but every sentence carries actionable 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?

With no output schema, the description fully compensates by describing both success and failure payloads, the failure reason categories, and the authentication expectation. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100% and the single 'jwt' parameter is already documented as 'the compact vc+jwt credential'. The description adds only the origin constraint ('issued by Aeroz'), which is marginal beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Check a passport credential ... against Aeroz's published signing keys') and scopes it to vc+jwt credentials issued by Aeroz, which clearly separates it from siblings like verify_chip and get_passport. An agent can tell exactly what operation is performed 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 clear context (verifying a credential's signature/revocation status) and names the alternative for a related need: 'compare passportVersion with get_passport'. However, it never states when not to use this tool or how it relates to verify_chip, so it stops short of full when/when-not 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?

Annotations already declare readOnly/ idempotent / non-destructive, so safety is covered; the description goes further by disclosing the shape of the answer (places plus how each place is known) and an important edge case: units with no recorded place are counted and listed but never placed. It stops short of noting result limits or pagination.

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

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

Three tight sentences, front-loaded with the core behavior and the unplaced-units caveat, then the input rule. Nothing is redundant with the title or schema.

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 read-only, non-destructive lookup with no output schema, the description covers return content, the null-place edge case, and the expected identifying input. Minor gaps remain around result size/pagination and the full meaning of 'how the place is known,' but nothing blocking for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a meaningful constraint the schema cannot express: although neither product nor lot is formally required, the caller should give product, lot, or both. It does omit any mention of the optional status filter, leaving that to the schema.

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

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

States a specific query: locating a product's or lot's units by last known place, enumerating the place categories (sites, partners, scans, in-transit shipments) it covers. That is far more concrete than the title, but it never names or distinguishes itself from nearby siblings like find_unit, trace_unit, or shipment_status.

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 closing sentence tells the agent what to supply (product, lot, or both), which implies invocation conditions. However, there is no explicit guidance on when to choose this over find_unit/trace_unit/shipment_status, nor any stated exclusions or prerequisites.

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