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?

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description explains exactly why: asking refreshes onboarding state and records the Q&A in the conversation, but 'sends nothing outside Aeroz and changes no product, shipment or passport data.' It also defines the grounded verdict values (computed/model/declined) and instructs honest relay of a declined answer — behavioral context well beyond the annotations.

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

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

Front-loaded with the core purpose, then example questions, then the grounded semantics and side-effect disclosure. The example questions and grounded definitions all earn their place, though the passage is on the longer side for a single-parameter tool.

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

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

With no output schema, the description carries the return-value burden and does so: it explains the grounded field and its three values. It also covers side effects (state refresh, conversation recording) and data-handling limits, so 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?

Only one parameter exists and schema coverage is 100%, with the schema already specifying 'The question, as the person asked it (at most 2000 characters).' The description only adds the 'plain language' framing, which is marginal beyond the schema. Baseline 3 applies when the schema does the documentation work.

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

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

States a specific verb and resource ('Ask this organisation's dedicated Aeroz agent a question... and get a grounded answer') and frames the scope as anything a business human would ask their account manager. It is clearly distinguishable from siblings like agent_conversation (which it points to for history) and onboarding_status. The example questions make the remit 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 concrete context ('anything a human at the business would ask their account manager') plus five example questions, which effectively routes the agent to this tool for account-status questions. It also names agent_conversation as where the Q&A lands. No explicit when-not guidance is provided, keeping it 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 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behaviour: counts are exact only for the units swept, the response self-reports when it hit its cap instead of implying full coverage, and an empty findings list explicitly does not mean compliance. That cap/empty-result semantics is exactly the kind of context structured fields 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?

Four sentences, front-loaded with the core action and output shape, with the caveat about empty findings placed last where it matters most. The four example queries are slightly repetitive but each maps to a distinct use case, so little is wasted.

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

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

With no output schema, the description carries the return-value burden itself and does so: findings grouped by failing check, affected unit counts, example units to open, and a truncation flag. Combined with the annotations, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning to `limit` by framing it as a sweep cap whose truncation is signalled in the response, and it reinforces the pack-omission behaviour as 'sweep under every pack'. It does not explain the status enum values, but the schema already lists them.

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 (sweep) and resource (this organisation's units) and precisely what is reported: which regulatory checks fail, how many units each affects, and example units to open. The example queries ('broken custody chain', 'what will not pass on 18 February') sharpen the scope considerably, though no sibling such as dpp_readiness or list_findings is named to draw an explicit 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?

Usage is conveyed through four concrete user questions that map cleanly onto the tool, giving an agent a clear sense of when this is the right call. It stops short of naming alternatives (dpp_readiness, list_findings, trace_unit) or stating when not to use it, so it is context without exclusions.

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

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

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?

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed-world). The description adds real value beyond that by disclosing the return shape (required fields, which are present, which missing) and a critical interpretation caveat that output must never be reported as compliance confirmation.

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

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

Three front-loaded sentences with zero filler: purpose first, return contents second, the compliance caveat last where it is most likely to be retained. 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?

With no output schema, the description correctly compensates by describing what is returned, and it flags the legal-interpretation limit of the output. For a single-parameter read-only assessment tool, an agent has everything needed to call and interpret it.

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

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

There is a single required parameter with 100% schema description coverage including concrete examples, so the schema already carries the load. The description implies that `category` resolves to a delegated act, but adds no syntax, format, or accepted-value detail beyond the schema.

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

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

States a specific verb (assess) and resource (readiness of a product category for an EU Digital Product Passport), and names the governing frame (the delegated act that applies). This clearly separates it from siblings like get_passport, verify_passport_credential, and chain_readiness 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?

Gives strong context on what the tool is for and, crucially, what it is not (a legal compliance determination). However it does not explicitly route the agent to an alternative such as verify_passport_credential or get_passport when actual verification or passport retrieval is the goal.

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 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?

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 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 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 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 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?

Annotations only establish read-only/idempotent safety; the description adds substantive behavioral context beyond that: tamper-evidence of the append-only log, the requirement that every failing check cite the clause it enforces, and an explicit disclaimer that verdicts are readiness signals and never a legal compliance determination. That last point materially changes how an agent should report 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 core capability is front-loaded in the first sentence, with usage questions and the compliance caveat following. It is dense but every sentence carries weight; the capitalized warning is emphatic rather than redundant, though the description runs slightly long for a two-parameter read tool.

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

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

With no output schema, the description does the work of describing the response shape (custody hops, tamper verdict, clause-cited check results, embedded disclaimer), which is enough for an agent to interpret results. It omits any mention of pagination or result-size limits for what could be a long custody history.

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

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

Schema coverage is 100% and both parameters are documented there, including the find_unit prerequisite. The description's mention of "DSCSA / the EU passport rules" loosely maps to the pack parameter's values but adds no syntax or format detail, so the schema is doing the heavy lifting — baseline 3.

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

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

The description names a specific resource (one serialized unit's full history) and enumerates exactly what it returns: custody hops from commissioning to dispensing, append-only log tamper status, and per-regulation verdicts. This is clearly separable from siblings like chain_readiness, dpp_readiness, and 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?

It gives concrete triggering questions ("where has this been", "who handled it", "is its record trustworthy", "does this unit pass DSCSA / the EU passport rules") and the schema tells the agent to use find_unit first when only a scan is available. It stops short of naming sibling alternatives or stating when not to use it (e.g., vs. chain_readiness).

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.