Zineps

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

Annotations already declare the write/non-destructive/non-openWorld profile, so the bar is lower. The description contributes the auth context (acts under the signed-in partner) and the 'password must meet portal rules' validation constraint, but says nothing about duplicate-email behavior, side effects, or 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?

Two short sentences, front-loaded with the action and scope. The second sentence partially restates schema requirements, though the 'portal rules' constraint 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?

All five parameters are documented in the schema and annotations cover the safety profile, but for a create/mutation tool the description leaves open duplicate handling, permission requirements, and success behavior — all things only prose could supply since there is no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one hint not in the schema — that the password is validated against portal rules rather than being any string — but says nothing about optional fields like intentId or country.

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 ('Create a merchant') and adds the scoping constraint 'under the signed-in partner'. It doesn't reconcile the naming mismatch between 'Customer' (tool name) and 'merchant' (description), but the action is unambiguous and no sibling tool competes for this operation.

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

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

No statement of when to use this versus LookupCustomer (e.g. check for an existing merchant first) and no exclusions or preconditions beyond 'signed-in partner'. The only guidance is a restatement of which fields are required, which the schema already enforces.

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

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

Annotations already declare this is a non-destructive, closed-world mutation, so the safety profile is covered. The description adds the meaningful precondition about the organisation being a customer of this partner, but says nothing about how a custom rate interacts with existing partner rates or what the margin fields do.

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

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

Two short sentences, front-loaded with the action and followed by the key constraint. No padding, though it is arguably under-specified rather than concise.

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, 5-required mutation with no output schema and zero schema descriptions, the description should explain margin semantics and the rate-creation model. It covers only one parameter and no return behavior, leaving the agent materially under-informed.

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 9 parameters, and the description only explains organisationId. Critical fields like marginType (a bare string with no enum), amount, contractPrice, and franchisePercentageMargin are left entirely unexplained, forcing the agent to guess valid values.

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

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

The description gives a specific verb and resource ('Add a customer-specific shipping rate') that clearly separates it from AddPartnerRate and AddPartnerSurcharge siblings. It stops short of naming an alternative, but the scope qualifier 'customer-specific' does the differentiation work.

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

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

It states one real prerequisite: organisationId is required and must be a customer of this partner — useful for avoiding a failed call. However, there is no guidance on when to use this versus AddPartnerRate, UpdateCustomRate, or the surcharge tools, so the agent must infer the decision.

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

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

Annotations already declare this is a non-readonly, non-destructive, closed-world mutation, so the safety profile is covered. The description adds the carrier-route prerequisite and clarifies marginType naming, but says nothing about what happens if a rate already exists on the route, whether values are overwritten, or what the response confirms.

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

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

Three short sentences, front-loaded with the action and scope constraint, then prerequisites, then the one tricky parameter. No filler or repetition.

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

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

This is an eight-parameter mutation with no output schema and no annotation detail about side effects, yet the description covers only two parameters and gives no guidance on idempotency, error conditions, or the interplay of amount/contractPrice/franchisePercentageMargin. Too thin for the complexity of the call.

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 carry parameter meaning. It does explain marginType as a name like 'FixedAmount' or 'Percentage' and flags carrierRouteId as required, but five of the eight parameters (amount, contractPrice, franchisePercentageMargin, intentId, externalLedgerCode) are left completely undefined — notably the relationship between the three monetary fields.

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

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

States a specific verb and resource ('Add a partner shipping rate') and explicitly excludes customer-specific rates, which implicitly routes the agent to AddCustomRate. It also separates it from AddPartnerSurcharge by naming 'rate'. It stops short of a fully explicit sibling comparison, but an agent can place it correctly.

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 exclusion of customer-specific rates implies when to pick AddCustomRate instead, and 'Requires a carrier route id' gives a prerequisite. There is no explicit 'use this when / not when' statement and no mention of the required carrierContractId or how partner vs. custom scoping actually differs.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: it is silent on duplicate handling (what happens if a partner surcharge already exists for that pairing), required permissions, or side effects on pre-invoicing despite the useInPreInvoicing flag.

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

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

Two compact sentences, front-loaded with the core action before the optional-scope qualifier. Nothing is wasted or buried.

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

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

With 9 parameters (4 required), full schema coverage and no output schema, the essentials are technically present. However, for a mutation tool the description omits conflict behaviour, the relationship between amount, carrierRateExVat and marginType, and VAT handling — gaps an agent would want filled before writing data.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's only parameter remark — that organisationId makes the surcharge customer-specific — largely restates the schema's own description of that field, adding no new syntax or interaction detail.

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 ('Add') and resource ('partner surcharge price for a carrier surcharge on a contract'), which is distinct from AddPartnerRate and GetPartnerCarrierSurcharges. It does not explicitly name the sibling to avoid (e.g. UpdatePartnerSurcharge), so differentiation is inferable rather than stated.

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

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

The clause 'Optional organisationId makes it customer-specific' hints at when to supply that field, but there is no explicit guidance on when to use this versus UpdatePartnerSurcharge or AddPartnerRate, nor any prerequisite about the contract or surcharge catalog needing to exist.

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 flag destructiveHint=true and readOnlyHint=false, so the write/irreversible profile is covered structurally; the description adds the genuinely non-obvious constraint that cancellation is only valid before carrier collection. It stops short of saying whether a refund/void is triggered or what the response returns on failure.

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

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

A single front-loaded sentence with the eligibility rule in the first clause and the API equivalence as supporting detail. Nothing is padding.

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

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

For a destructive, open-world mutation with no output schema, the description covers eligibility but omits outcome (what happens to the label record, refunds, or tracking), failure modes, and required permissions. The annotations carry the safety signal, but the post-call behavior remains unstated.

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

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

Schema description coverage is 100%, so both parameters (labelId, intentId) are already documented in the schema. The description adds no format, sourcing, or correlation-ID guidance beyond that, 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 ('Cancel') and resource ('a label') plus a scoping precondition ('the carrier has not collected yet') and anchors it to the equivalent REST endpoint. This separates it from read-side siblings like GetLabel and from RemakeLabel, though no sibling 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?

The precondition 'has not collected yet' effectively states both when to use it and when it will fail, which is the key eligibility rule for a cancellation. It does not name alternatives (e.g., RemakeLabel for already-collected labels) or mention where to check collection status.

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 destructiveHint=true and openWorldHint=true, so the agent knows this is a write operation with external side effects. The description adds the useful prerequisite about contract/product selection, but it does not explain cost, irreversibility, or error behavior beyond what annotations provide.

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

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

Two sentences, zero waste, and the precondition is front-loaded immediately after the action. 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 destructive, open-world write tool with no output schema, the description is minimal. It covers the core action and one important precondition, but an agent might still want to know whether the label is billable, idempotent, or what a success response contains.

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

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

Schema description coverage is 100%, so both parameters (orderId and intentId) are fully documented in the schema. The description does not add meaning beyond the schema, which is acceptable but not value-adding.

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

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

The description states a specific verb and resource: 'Create a shipping label for a Zineps order.' This clearly distinguishes it from siblings such as CancelLabel, GetLabel, and RemakeLabel. An agent can identify the tool's function without opening the schema.

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

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

The description gives a clear precondition: 'The order must already have carrier contract and product selected in Zineps.' That tells the agent when the tool is usable, though it does not name alternatives or explicitly state when not to use it.

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

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

The description adds useful behavioral context beyond annotations: it calls an external live carrier API, returns carrier HTTP request/response bodies, and writes LabelLog entries. This aligns with openWorldHint=true and readOnlyHint=false, and the write side effect is especially valuable to disclose.

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

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

The description is three focused sentences, front-loads the action and resource, and each sentence contributes useful information: purpose, prerequisite, and observable behavior.

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 debug tool with no output schema, the description says enough about what it does, what it returns, and what side effect it has. It does not cover failure modes or external API constraints, but annotations and schema already carry the safety and parameter details.

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 three parameters are already documented in the schema. The description adds only contextual prerequisite information about the shipment draft, not parameter-specific meaning beyond what the schema provides.

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

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

The description states a specific action and resource: call the carrier live rates API for an existing shipment draft. It is clear and distinct from generic rate or label tools, though it does not explicitly name a sibling alternative.

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

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

It implies the debug use case and states a prerequisite that a carrier contract and product must already be selected in the draft's Shipping snapshot. However, it gives no explicit when-not-to-use guidance or comparison to sibling investigation/rate tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral note that large labels may be truncated in JSON, but says nothing about auth, size limits, or when each format 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?

Two short sentences, front-loaded with the core action and with zero filler. The truncation caveat is appended compactly rather than buried in prose.

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 tool with annotations covering safety, this is nearly adequate. However, with no output schema, the description should explain what the returned bytes look like (base64 string, truncation behavior, format selection), and the format ambiguity is 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 100%, so labelId and intentId are documented in the schema and the baseline is 3. The description adds no meaning for either parameter and instead introduces output formats that have no corresponding parameter, which may confuse an agent looking for a format switch.

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 action and resource: re-creating label bytes for download, with the output formats (PDF, ZPL base64) named. It is clearly distinct from lookup tools like GetLabel/FindLabel, though no sibling 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?

There is no guidance on when to use this instead of GetLabel, FindLabel, RemakeLabel, or SendLabelToPrintNode. The only usage-adjacent content is the truncation caveat, which tells an agent about limits rather than about selection.

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

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

Annotations already establish that this is a read-only, open-world, non-destructive operation. The description adds useful behavioral context beyond annotations, including that numeric queries may match external order IDs or prefixed display numbers and that recipientName disambiguates ambiguous matches. It does not cover auth, rate limits, or error behavior.

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

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

The description is front-loaded with the core action and is appropriately sized for a seven-parameter lookup tool. The sentences are dense but every sentence contributes relevant lookup or disambiguation context.

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 multi-platform read-only lookup with full schema coverage and existing safety annotations, the description is nearly complete. It covers the action, accepted identifiers, optional filters, and ambiguity handling, though it does not describe return shape or error behavior in the absence of an output schema.

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 parameter descriptions already carry the baseline burden. The description still adds meaning beyond the schema by explaining platform-specific order-number formats, when shopId narrows results, and how recipientName and organizationQuery help resolve unknown-shop cases.

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

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

The description states a specific verb and resource: fetch an order from live Shopify, WooCommerce, or CCV Shop APIs by order number or external order ID. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as FindOrder or OrderInvestigation.

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

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

The description gives parameter-level usage guidance, such as using shopId to narrow a search and recipientName to disambiguate matches. However, it does not say when to use this tool instead of alternatives like FindOrder or OrderInvestigation, so tool-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that no organisationId scoping is required, which is genuine context, but says nothing about result count behavior, ordering, or what happens when multiple invoices match.

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

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

Two short sentences, front-loaded with the action and resource, with zero filler. The phrase 'No organisationId needed' is terse to the point of being cryptic about why that matters, which costs a point.

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 lookup with a fully documented four-parameter schema and annotations covering the safety profile, the description is nearly sufficient. The one real omission is its relationship to the InvoiceInvestigation sibling, which affects tool selection.

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 schema documents limit, intentId, and unpaidOnly. The description adds only the meaning of query (invoice number or email), which the schema already states. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource (find customer invoices) and names the two accepted lookup keys (invoice number or customer email). It does not distinguish itself from the sibling InvoiceInvestigation, so an agent cannot tell from the description which of the two to reach for.

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 lookup keys and by the note that no organisationId is required, which suggests a quick standalone lookup. There is no explicit when-to-use versus InvoiceInvestigation, and no exclusions or alternatives named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond them: it does not say whether matching is exact or fuzzy, whether partial strings are allowed, or whether multiple labels can be returned — a meaningful ambiguity for a lookup tool.

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

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

A single front-loaded sentence with no filler, which is appropriately sized for a simple lookup. It is arguably too terse, since the same brevity that keeps it clean also leaves the routing question unanswered.

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

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

There is no output schema, and the description does not state that this returns a list bounded by the limit parameter (default 10), nor what happens when nothing matches. For a tool in a namespace with four or five near-duplicate lookup siblings, this is not enough to call it correctly.

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

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

Schema description coverage is 100%, so both 'query' and 'limit' are documented in the schema and the baseline of 3 applies. The description restates the query keys but does not add matching semantics or explain how 'query' auto-detects between track & trace, label id, reference and usage id.

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

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

The description gives a specific verb (Find) and resource (shipping labels) plus the four lookup keys, which is more than a restated title. However, it never distinguishes itself from close siblings such as GetLabel, SearchShippingLabels, LookupByTrackTrace and ListRecentLabels, all of which appear to operate on the same resource.

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

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

There is no statement of when to use FindLabel versus SearchShippingLabels, GetLabel or LookupByTrackTrace, which are the obvious alternatives in a crowded label namespace. The agent is left to infer that this is a general-purpose lookup rather than a narrower 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, non-destructive, closed-world), so the description's real contribution is the non-obvious matching behavior: numeric queries can hit both externalOrderId and prefixed display numbers, with a concrete example. It does not say whether matching is exact or prefix/substring, nor whether results are ordered or paginated beyond 'limit'.

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, no filler, with the searchable fields front-loaded and the numeric-matching nuance immediately after. Every sentence carries information an agent cannot get from the name alone.

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

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

For a low-complexity read-only search with a fully described schema, this is adequate but incomplete: with no output schema, the description never says what an order record contains or how many results come back by default. It also omits what happens when nothing matches (empty list vs error).

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

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies the accepted query forms and that shopId narrows to a single shop, but adds nothing about limit, openOnly, or intentId.

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 ('Find orders in Zineps') plus three query modes (order number, track & trace, recipient email), which is clearly more than the title restates. It never names a sibling (e.g. LookupByTrackTrace, OrderInvestigation, FetchWebshopOrder), so an agent must infer the boundary itself.

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 query modes imply when the tool applies, but there is no explicit when-to-use/when-not guidance and no mention of the track-trace-centric siblings that overlap with it. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful context beyond annotations: it states that no organisationId is needed and that the result includes a user profile and quick stats. The phrase 'quick stats' remains somewhat vague, but the added behavioral context is solid.

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

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

Three short sentences, front-loaded with the core action and lookup keys. The prerequisite note and return summary follow efficiently with no wasted text.

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

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

For a simple read-only lookup with fully documented parameters, the description covers what the tool does, the required input shape, a key prerequisite, and the return content. The only notable gap is that it does not route the agent away from the similar sibling LookupCustomer.

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 three parameters are already documented in the schema. The description adds little parameter-specific detail beyond implying the query format, which the schema itself also lists. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (Find) and resource (customer/user) plus the accepted lookup keys (email, company name, person name). It does not distinguish itself from the sibling LookupCustomer, which likely serves a similar purpose.

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

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

Usage is implied by the lookup keys, and the note that organisationId is not required gives useful context. However, there is no explicit guidance on when to use this versus LookupCustomer or GetMyInfo, and no exclusions are stated.

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

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

The annotations already declare this as a safe, read-only, closed-world operation, so the description's burden is lighter. It adds useful behavioral context by saying the analytics cover the signed-in merchant or a partner's customer set and by listing the kinds of results returned, though it does not describe response shape or limits in more 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?

The description is three compact sentences, front-loaded with the main purpose, followed by date format and partner-specific parameter behavior. It is dense but wastes no words.

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

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

For an analytics tool with no output schema, the description gives a useful summary of returned categories and covers partner scoping and date format. It does not fully describe the chart or response structure, but it is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining partner aggregation behavior: omit organisationId to analyze the whole book, or pass one customer organisation id for that customer.

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 resource and scope: full shipment analytics for the signed-in merchant or a partner's customers, and it enumerates the included metrics (order/label/return counts, carrier mix, delivery performance). It is clear what the tool does, but it does not explicitly distinguish itself from nearby reporting/partner tools such as PartnerSummary or SummarizeUsageRecords.

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 context is implied by the merchant-vs-partner framing and by the instruction that partners omit organisationId for the whole book or pass one customer organisation id. However, the description does not explicitly state when to use this tool rather than sibling reporting or investigation tools, and it gives no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the returned field set, which is genuine value given there is no output schema, but it says nothing about behavior for unknown IDs, partial matches, or result ordering.

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

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

A single front-loaded sentence with no filler. The verb, the input format, and the returned fields all appear in one pass with nothing extraneous.

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

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

For a read-only, two-parameter lookup with no output schema, the description covers input shape and concrete return fields, which is the main thing an agent needs. It falls short only on edge-case behavior (invalid IDs, batch limits), which is a minor gap for a resolver tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the comma-separated example for carrierRouteIds and the optional correlation role of intentId. The description merely restates the comma-separated ID format, adding no syntax or constraint beyond the schema; 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 ('Resolve') and resource ('carrier route IDs') and enumerates exactly what the caller gets back: carrier, product code, origin/destination countries, weight band. No sibling tool deals with carrier routes, so the agent can tell it apart from the label/order/surcharge tools without opening the schema.

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

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

The phrase 'Resolve ... to lane details' implies the lookup use case, but there is no explicit statement of when to reach for this tool versus the surcharge or rate tools, nor any prerequisite or exclusion. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the concrete payload facets (order link, carrier, contract, product), but says nothing about not-found behavior or what happens when an invalid id is supplied.

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

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

A single sentence, front-loaded with the subject and immediately followed by the returned fields. Nothing is padded and nothing is buried.

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

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

There is no output schema, so the description must carry the return-value story; it does so at a high level by naming four payload elements. It is adequate for a simple two-parameter read, though it omits total field coverage and error cases.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema, which sets the baseline at 3. The description reinforces that the key is a 'label usage id', but adds no meaning for the optional intentId correlation parameter beyond what the schema already states.

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

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

The description gives a specific verb-resource pair for a single record ('Full details for one label usage id') and enumerates the returned facets: order link, carrier, contract, product. It does not, however, differentiate itself from nearby siblings such as FindLabel or GetLabelsForOrder, so an agent must infer the distinction from names alone.

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

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

No statement of when to use this versus FindLabel, GetLabelsForOrder, or ListRecentLabels, and no prerequisites or exclusions. The phrase 'one label usage id' only weakly implies single-record lookup rather than search.

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, non-destructive, closed-world), and the description adds real value beyond them: the payload contents (request/response bodies), redaction of sensitive data, the 100 KB per-body cap, and the Admin/Superuser access requirement.

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

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

One front-loaded sentence packing the verb, resource, returned payload, size/redaction constraints, and auth prerequisite with zero 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 carries the burden of describing the return payload, and it does so. It leaves minor gaps such as not-found behavior and whether every label has a log, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the optional intentId correlation field. The description only restates that lookup is by id and adds no format or edge-case detail; 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 ('Get one label creation HTTP log by id'), including the singular scope that separates it from the sibling search_label_logs. It never names that sibling, so the differentiation is implied 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?

The 'by id' scoping implies this is the single-record retrieval counterpart to search_label_logs, and the admin prerequisite gives a use condition. However, there is no explicit statement of when to use this versus search_label_logs first to find an id.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that results are scoped to a single order; it does not say what happens when an order has no labels, whether results are paginated, or what fields a label carries.

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 short sentence with the key constraint (order-scoped, GUID identifier) front-loaded and zero filler. Nothing is buried or redundant.

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 is the only place a caller could learn what a returned label looks like or how results are shaped, and it does not cover that. For a simple two-parameter read it is minimally sufficient, but a consumer cannot predict the response.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that orderId is a WebOrder id / GUID but adds no format, syntax, or interpretation detail beyond that, and says nothing about the optional intentId correlation 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 (List) and resource (labels) scoped to a Zineps order / WebOrder GUID, so the agent knows this is a per-order label listing. It does not name or contrast with near-siblings like GetLabel, ListRecentLabels, or FetchWebshopOrder, so the agent must infer the boundary.

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

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

The phrase 'created for a Zineps order (WebOrder id / GUID)' implies the preconditions (you must already know the order id) but gives no explicit when-to-use or when-not guidance. No alternative tool is mentioned, so selection against GetLabel or FindLabel 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's contribution is limited to noting that results include recent tracking events. It does not disclose data freshness, whether the carrier is queried live, rate limits, or behavior when the carrier has no events yet.

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

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

One sentence, front-loaded with the resource and result content, with no filler. It is efficient, though the brevity comes partly from omitting guidance rather than from tight editing.

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 describing return values; it sketches them (status plus recent events) but not the shape, count, or freshness of those events. For a read-only tracking tool with full schema coverage, this is adequate but leaves real gaps.

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

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

Schema coverage is 100%, so both parameters are documented, establishing a baseline of 3. The phrase 'label usage id' does add a small disambiguation over the schema's 'Label usage id (integer)', but it adds nothing about intentId's correlation-ID semantics or format.

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

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

States a specific resource (carrier tracking status plus recent tracking events) scoped to a label usage id, which is clear and concrete. It lacks a verb and never distinguishes itself from close siblings like GetShipmentStatus, GetShipmentStatuses, or LookupByTrackTrace, so an agent must infer the boundary.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives despite a crowded sibling set of tracking/lookup tools (GetShipmentStatus, GetShipmentStatuses, LookupByTrackTrace, InvestigateLabelByTrackTrace, get_label_log). The agent is left to guess which tracking tool applies.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds that it returns authenticated user scope, partner context, and user list for partners, which is useful context about the data returned, but it does not elaborate on authentication requirements, response format, or rate limits.

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

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

The description is a single, front-loaded sentence that clearly states what the tool returns. There is no unnecessary text, and the key information is presented 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?

Given the tool has no parameters, no output schema, and annotations covering the safety profile, the description is largely complete for an agent to understand what data it returns. A minor gap is the lack of detail about the structure of the returned data, but for a simple read-only tool, this is acceptable.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline score for no parameters is 4, as the schema is trivially complete and the description need not compensate.

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

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

The description states a specific verb ('Return') and three specific resources ('authenticated user scope', 'partner context', 'user list for partners'), making the tool's purpose clear. It does not explicitly differentiate itself from siblings like FindUser or ListBrands, but the focus on the authenticated user's own info is distinct enough.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. It merely describes the return content without indicating the appropriate context for invocation.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real value with the authorization rule that partners only see their own surcharges, but it says nothing about the limit/pagination behavior (default 100) or whether exceeding the limit truncates 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?

One compact sentence with the scope and payload front-loaded before the access rule. No filler, though it is on the terse side for a 7-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?

For a read-only filtered list with a fully documented schema and no output schema, the description plus annotations give an agent enough to call it correctly. The main residual gap is the absence of any routing hint against SearchCarrierSurcharges.

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 every parameter including amount, carrier, search, and carrierContractId is already documented with examples. The description only loosely echoes 'margin, contract' and adds no syntax or constraint details beyond the schema, which is the expected baseline 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 and resource ('List partner carrier surcharges') and enumerates what is returned (margin, contract, linked carrier products), plus a scoping constraint ('partners only see their own surcharges'). It never names the closely related sibling SearchCarrierSurcharges, so an agent must infer which one to pick.

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

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

The partner-scoped nature implies when it applies (retrieving surcharges for a given partner), but there is no explicit guidance on when to use this versus SearchCarrierSurcharges or UpdatePartnerSurcharge/AddPartnerSurcharge. Usage is inferred rather than stated.

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

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

The description discloses behavior the annotations cannot: it refreshes carrier status only when older than 12 hours, persists tracking events and changed status fields, and degrades to stored-only reads for read-only credentials. This coherently explains why readOnlyHint is false and openWorldHint true, giving the agent a real picture of side effects and freshness.

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

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

Three dense sentences with zero padding: purpose first, side effects and refresh policy second, credential caveat third. Every sentence carries information an agent needs.

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

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

With no output schema, the description still conveys the return concept (current status, tracking events) and the API mapping. It stops short of describing the response shape or what 'status fields' means, which would be the last gap for a tool with no output schema.

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 labelId and the optional intentId correlation ID are already documented. The description adds no parameter-level detail beyond 'one label', 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 and resource: 'Current shipment status for one label.' The 'one label' scoping implicitly distinguishes it from the plural sibling GetShipmentStatuses, but it never names GetLabelTrackingStatus or GetLabelsForOrder, so the agent must infer differentiation.

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

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

It defines a real usage condition — read-only credentials get stored status without refreshing — which is genuinely useful. However, it gives no explicit when-to-use guidance versus the closely related siblings (GetShipmentStatuses, GetLabelTrackingStatus), leaving routing 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?

This is a strong disclosure: it explains that the call refreshes stale carrier data and persists tracking events, which is exactly why readOnlyHint=false, and it clarifies that read-only credentials get stored status without refresh or persist. It also documents the notFound behavior for out-of-scope ids — meaningful side effects the annotations alone could not 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 short sentences, front-loaded with the core purpose, followed by side effects and the credential caveat. Every sentence carries distinct information and nothing is repeated.

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 covers the key return nuance (notFound for out-of-scope ids) and the mutation side effects. The main remaining gap is the lack of routing guidance against the near-duplicate single-id and tracking-status siblings.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description only restates the 'max 100' limit on labelIds. It adds nothing about intentId, the correlation ID parameter, beyond what the schema says. 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 with scope: 'Shipment status for up to 100 label ids.' An agent immediately knows this is a batch status lookup. It does not, however, distinguish itself from the very similar siblings GetShipmentStatus (singular) or GetLabelTrackingStatus, leaving ambiguity about which to pick.

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

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

Batch usage is implied by the 'up to 100 label ids' framing, and the read-only-credential branch is described, but the description never says when to choose this over GetShipmentStatus or GetLabelTrackingStatus. There are no explicit exclusions or alternatives named despite several overlapping siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful context by flagging that these are *raw GraphQL* line items (unprocessed upstream payloads) and that one field is a resolved/derived value, but it omits error behavior, external-API failure modes, and any rate-limit or auth caveats expected of an open-world Shopify call.

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

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

Two sentences, front-loaded with the purpose and the returned field set, then the required inputs. The field enumeration is dense but each item carries identifying value; nothing is filler, though the list pushes toward the long side for a simple 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 compensates by enumerating the fields returned, which is exactly what an agent needs to judge fit. Gaps remain around result shape (single order assumed? multiple line items?), pagination, and behaviour when the external Shopify id resolves to nothing, but the core contract is conveyed.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description largely restates them (shopId as ApiCredential.Id, order number examples) rather than extending them. The optional intentId correlation parameter is not mentioned at all, and no format constraints beyond the schema example are added. 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 ("Fetch raw Shopify GraphQL line items for an order") and enumerates the return payload fields (product, variant, SKU, customAttributes, product-linked flag, resolved material). This is clearly distinguishable from generic order tools like FetchWebshopOrder or FindOrder, though it does not name a sibling it is exclusive of.

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 second sentence tells the agent which identifiers to supply (shopId, order number like BU741087, or external order id), which is real usage guidance. It says nothing about when to prefer this over FetchWebshopOrder/FindOrder, nor when this tool is inappropriate (e.g. non-Shopify shops), so selection guidance remains implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false with openWorldHint=false, so the safety profile is covered and the description only needs to add discovery behavior. It does add that output is role-aware and covers workflows, but with zero parameters it never explains how the role is inferred — from caller identity, token, or defaults — which materially affects what the agent receives.

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

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

A single front-loaded sentence with the verb and the payload up front; no filler, no restatement of the title. Well sized for a zero-parameter discovery 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 is the only place the return value can be characterized, and 'guide to tools and investigation workflows' is only a rough sketch — structure, length, and whether it lists workflows by name are unknown. For a meta-tool whose entire value is the shape of the guide it returns, that is a meaningful 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% on an empty object, leaving no semantic gaps to fill.

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: 'Return a role-aware guide to available Zineps tools and investigation workflows.' That is clearly distinguishable from every sibling, which are concrete data operations rather than meta/discovery. The only ambiguity is what 'role-aware' means and how the role is determined.

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

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

No explicit when-to-use: nothing tells the agent to call this first, or on failure, or when it is unsure which of the ~46 siblings applies. There are no exclusions and no alternatives ('call the concrete tool directly if you already know it' would have been valuable). Usage has to be inferred from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered; the description adds real value by disclosing that the call fans out across DB, Shopify, and Nova Post systems and returns a comparative material analysis (sent vs current code). It stops short of noting auth requirements, rate limits, or behavior when a track trace 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?

Two sentences, front-loaded with the core action, then the return payload. The long enumeration is dense but each item is load-bearing information about what the caller receives from a tool with no output schema.

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

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

With no output schema, the description does the heavy lifting by enumerating the returned fields, which is exactly what an agent needs to decide whether this call answers its question. Missing are failure/empty-result behavior and any note on the optional intentId, keeping it below full marks.

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% with only two parameters, both documented, so the schema already carries semantics. The description reinforces that the lookup is keyed by track & trace but says nothing about the optional intentId correlation parameter, so it adds little 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 and resource ('one-call label/material investigation by track & trace') and enumerates exactly what comes back (label createdAt, order, DB line items, Shopify line items, Nova Post material comparison). That payload enumeration implicitly separates it from thinner siblings like LookupByTrackTrace or GetLabelTrackingStatus, though it never names an alternative directly.

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

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

The phrase 'one-call ... investigation' implies this is the consolidated option rather than a single-purpose lookup, but there is no explicit when-to-use/when-not guidance and no mention of LookupByTrackTrace, OrderInvestigation, or InvoiceInvestigation, all of which plausibly overlap. Usage is inferable but not 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value beyond the schema by disclosing the shape of the returned data (header, line items, label count for the period, related surcharges), which matters since there is no output schema; it stops short of mentioning error behavior for unknown invoice numbers.

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

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

A single front-loaded sentence identifying the resource, the key, and the returned content with zero filler. Every clause carries information the agent can use.

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 only two parameters and no output schema, the description covers the essential need by listing what the investigation returns. Minor gaps remain: no statement of what happens when the invoice is not found, no pagination or size expectations, and no explicit routing from FindInvoice.

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

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

Schema description coverage is 100%, so both parameters (invoiceNumber, intentId) are already documented in the schema. The description only echoes that lookup is by invoice number, adding no syntax, format, or correlation-ID guidance beyond what the schema provides, 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 ('invoice deep-dive') and resource ('by invoice number') and enumerates what the result contains: header, line items, label count in period, related surcharges. It is clear what the tool does, but it does not differentiate itself from sibling 'FindInvoice', so an agent must infer that 'deep-dive' means full detail rather than a lookup.

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

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

The phrase 'deep-dive' implies this is the detailed follow-up to a search, and the sibling names FindInvoice and OrderInvestigation make that contrast inferable, but the description never states when to use this versus those alternatives or what prerequisites exist (e.g. whether the invoice number must come from FindInvoice).

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds only a REST-endpoint cross-reference; it says nothing about result ordering, empty-list behavior, or how the company/org scoping affects the result.

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

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

One short sentence with no wasted words, but it is a fragment ('Brands for the company') rather than a front-loaded statement of action and result. Brevity here comes at the cost of information rather than being earned.

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

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

No output schema exists, so the description should carry the burden of telling the agent what a brand record contains or what the list looks like; it does not. For a simple read tool this is a clear gap, though not fatal.

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 both optional params (intentId, organisationId) are well documented in the schema, so the baseline 3 applies. The description contributes no additional parameter context.

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?

Names the resource (brands) and its scope (the signed-in company) and cross-references GET /api/Brands, so an agent can infer a read-list operation. But it is a noun phrase with no verb, and it never states whether it returns all brands, top-N, or a filtered set.

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

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

There is no when-to-use guidance and no comparison to alternatives such as ListSenders, ListContracts, or the various Lookup/Search tools. The agent is left to guess that this is the only brand-listing path.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds one genuinely useful trait beyond that — that API keys and passwords are excluded from results — but says nothing about pagination, result size, or filtering behavior for a list operation.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the exclusion note. No filler, though the API-endpoint reference is slightly redundant given the tool name.

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

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

With no output schema, the description should convey what a contract record looks like or how results are shaped, but it only says what is excluded. Adequate to call correctly, incomplete for interpreting results.

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%, with both optional parameters (intentId, organisationId) fully documented including the default-organisation behavior. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description identifies the resource precisely — carrier contracts the company can ship with — and anchors it to a known API endpoint (GET /api/Contracts). The verb 'list' is only implied by the tool name, but scope is clear enough to distinguish it from sibling list tools like ListBrands or ListSenders.

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

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

There is no guidance on when to call this tool versus alternatives, no prerequisites, and no mention of related siblings such as AddPartnerRate or GetPartnerCarrierSurcharges. The API-endpoint reference is informational, not a usage 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, destructiveHint=false, and openWorldHint=false, so safety is clear. The description adds scope and ordering ('newest first'), but does not mention pagination, return shape, or whether results are capped by the limit parameter.

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 focused sentence with no wasted words. The key scope and ordering information is front-loaded.

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

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

For a simple read-only listing tool with no required parameters, full schema coverage, and clear annotations, the description is largely sufficient. It could be improved by noting pagination or maximum result behavior, but the schema already covers the limit cap.

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 parameters like limit, carrier, dateFrom, and intentId are fully documented in the schema. The description adds no extra parameter semantics beyond what the schema provides, which is the baseline expectation when coverage is complete.

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

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

The description states a specific verb and resource: 'List the most recently created shipping labels,' with scope ('in your scope') and ordering ('newest first'). It is clear what the tool returns, though it does not explicitly differentiate itself from sibling tools like SearchShippingLabels or FindLabel.

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

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

The phrase 'most recently created' implies a use case for recent-label lookups, but there is no explicit guidance on when to choose this tool versus SearchShippingLabels, GetLabelsForOrder, or FindLabel. Usage is implied rather than directed.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that this is a mirror of GET /api/Senders, but says nothing about auth requirements, rate limits, or whether results are paginated.

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

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

Two short sentences with zero filler, and the core statement of what the tool returns is front-loaded before the useful detail about the Code field.

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 two-optional-parameter list tool with annotations covering safety and no output schema, the description is nearly sufficient. The note about the Code field partially compensates for the missing output schema, though response shape beyond that field remains unstated.

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

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

Schema description coverage is 100%, so both optional parameters (intentId, organisationId) are already documented in the schema. The description adds no further meaning to either parameter, which is acceptable at the baseline but not more.

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 ('sender addresses for the company') and even pins it to the underlying endpoint GET /api/Senders, so an agent knows exactly what data comes back. It stops short of an explicit verb like 'list', and no sibling tool covers senders, so differentiation isn't really needed here.

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

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

There is no explicit when-to-use statement or exclusion, but the closing clause ('Code is the sender id used when creating a label') implicitly routes the agent toward CreateLabelForOrder. That link is only implied, not spelled out with a condition.

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

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

Annotations already declare this a safe, non-destructive, closed read. The description adds modest context by identifying it as a passthrough of GET /api/Shippingmethods, but says nothing about the organisationId scoping default, empty-result behavior, or how the optional filters combine.

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

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

Two short sentences with zero filler; the resource definition is front-loaded and the clarifying note about ProductCode follows. Nothing is redundant with the title.

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

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

For a read-only, all-optional-parameter list tool with full schema coverage and no output schema, the description covers what the tool returns (shipping methods / product codes) and how that value is consumed. Minor gap: it does not describe the returned fields such as carrier or product name formatting.

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 nine parameters are already documented in the schema (units, ISO-2 examples, 'not a numeric id', the ListContracts cross-reference). The description adds no parameter-level meaning beyond noting ProductCode maps into CreateLabelForOrder, 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 the specific resource ('Shipping methods available for a route') and ties it to the underlying REST endpoint, plus clarifies its downstream use for ProductCode. It never names a sibling tool, so differentiation from ListContracts or SearchParcelShops is left implicit, but the verb+resource 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?

Usage is implied rather than stated: the ProductCode sentence hints the tool is a prerequisite step before creating a label, and the route phrasing implies filtering by origin/destination. There is no explicit when-to-use / when-not-to-use guidance or reference to the competing contract and parcel-shop tools.

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

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

Annotations already establish readOnly, non-destructive, closed-world behavior, and the description adds the substantive detail that the response aggregates usage records, matching orders, label surcharges, and return orders for one code. It omits volume/pagination limits and what happens when no shipment matches, which keeps it short of a 5.

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

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

Two sentences, zero filler: the action and its scope come first, then the payload contents. Nothing repeats the title or restates the obvious.

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

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

For a read-only lookup with no output schema, enumerating the returned record types is the right move and largely covers completeness. The gap is disambiguation: with InvestigateLabelByTrackTrace and LookupByTrackTraceBatch in the sibling set, the description should say why an agent picks this one, and it doesn't.

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

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

Schema coverage is 100%, so both trackTrace and intentId are already documented in the schema. The description reinforces exact-match semantics of the tracking code but says nothing about the optional intentId correlation parameter, so it adds only marginal value over 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 ('Investigate') and resource ('a shipment') scoped to an exact track & trace code, then enumerates the returned record types. The 'exact' qualifier implicitly separates it from LookupByTrackTraceBatch, but the near-identical sibling InvestigateLabelByTrackTrace is never mentioned, so full sibling differentiation is missing.

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 'exact track & trace' framing implies this is the single-code lookup rather than the batch variant, which is useful implied guidance. However there is no explicit when-to-use / when-not statement and no pointer to InvestigateLabelByTrackTrace or GetLabelTrackingStatus, which an agent would need to choose correctly.

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, non-destructive, closed-world behavior, so the description's added value is the batch cap and the stated return contents (labels, orders, surcharges keyed by track & trace). It does not cover partial failures or invalid-code handling, but it adds meaningful behavioral context beyond annotations.

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

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

Two tight sentences with no waste: the first covers scope and capacity, the second covers return contents. It is front-loaded and appropriately sized.

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 adequately discloses what is returned (labels, orders, surcharges keyed by track & trace) and the batch limit. Minor gaps remain around output shape and handling of invalid or partial track & trace codes, but the core call contract is covered.

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

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

Schema coverage is 100%, so both parameters are documented in the schema. The description adds the important 200-code batch limit on trackTraces, which is not in the schema; intentId semantics remain delegated 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 (lookup), resource (shipment/track & trace), and scope (batch up to 200), making it distinguishable from the singular LookupByTrackTrace. It does not explicitly name the sibling or contrast the two, but the batch scope is clear.

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 batch context and 200-code limit imply when to use it, but the description gives no explicit exclusions, prerequisites, or alternatives such as LookupByTrackTrace for single lookups or InvestigateLabelByTrackTrace for investigations.

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

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

Annotations already declare this as a safe read-only lookup with no destructive effects. The description adds useful behavioral context by disclosing the breadth of returned data, including orders, invoices, tickets, and label stats, which helps the agent anticipate the response.

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

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

A single dense sentence front-loads the core purpose and aggregates the returned data categories without 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 two-parameter read-only lookup without an output schema, the description gives enough detail about what the customer 360 view contains. The optional intentId correlation behavior is left entirely to the schema, 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 coverage is 100%, so both the query and intentId parameters are already documented. The description confirms that query may be an email, company, or name, but adds little beyond the schema's own parameter descriptions.

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

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

The description names the specific resource (customer) and what the lookup returns: profile, recent orders, invoices, subscription, open tickets, and label stats. It is clear enough to distinguish this from narrower siblings like FindOrder or FindUser, though it does not explicitly name those alternatives.

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 identifiers it accepts (email, company, or name) and the aggregate customer view, but there is no explicit guidance on when to choose this over FindUser, FindOrder, or InvoiceInvestigation.

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

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

Annotations already declare read-only, non-destructive, and non-open-world behavior. The description adds useful payload context by listing order details, usage records, payment orders, and related tickets, but does not mention permissions, aggregation behavior, or not-found handling.

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

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

The description is a single front-loaded sentence with no filler. The included-data list is compact and useful.

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 helpfully lists the main data returned by the investigation. It is nearly complete, though it stops short of explaining investigation boundaries, alternatives, or error cases.

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

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

Schema description coverage is 100%, and the schema documents both query and intentId. The description restates that the query can be an order number or track & trace, but does not mention intentId or add syntax details 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 resource and scope ('Full order investigation') and the supported identifiers, and enumerates the included data. It does not explicitly differentiate itself from sibling order-lookup tools such as FindOrder or FetchWebshopOrder.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling tools are named as alternatives. The accepted identifiers imply usage, but the agent must infer how this differs from other order and track-trace tools.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), but the description adds the non-obvious access-control behavior: partners are silently scoped to their own data while admins may supply partnerId. It also anchors the default scope to the current month. It does not mention currency of revenue or whether scoping failures error out.

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

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

Two compact sentences with zero filler; the metric list and the caller-role rule are both front-loaded and immediately actionable.

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 listing the four returned metrics, and it covers the access-scoping nuance. Minor gaps remain around units (currency of revenue) and whether the month filter applies uniformly to all metrics.

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 schema already documents month format/default, partnerId being admin-only, and intentId as a correlation ID. The description's mentions of current month and the admin/partner distinction restate rather than extend 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 names the resource (partner dashboard) and enumerates exactly the metrics returned: label count, revenue, open tickets, unpaid invoices. A specific verb is absent and it does not explicitly distinguish itself from siblings like GetAnalytics or SummarizeUsageRecords, so it lands just below the top band.

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?

"Partners see own data; admins pass partnerId" gives a clear conditional rule for how to invoke it depending on caller role. It stops short of stating when to prefer this over GetAnalytics or SummarizeUsageRecords, so no exclusions or alternatives are 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 already flag destructiveHint=true and openWorldHint=true, so safety framing is partly covered. The description adds that a brand-new label is minted rather than reusing the old one, but it never says what happens to the original label (voided? still billable?), nor whether the operation incurs a new carrier charge — material gaps for a destructive, open-world mutation.

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

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

Two short sentences, zero redundancy, with the core action front-loaded and the important edge case (already-complete orders) placed second.

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

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

For a destructive, open-world mutation with no output schema, the description should say whether the returned artifact is a new label ID and what the caller does with it. It covers the conceptual model well but leaves the outcome of the call and the fate of the prior label unspecified.

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; the description adds meaning by explaining that the order, carrier contract and product are all inherited from labelId, reinforcing what the schema's "copy shipment settings from" implies. It says nothing extra about intentId, 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?

States a specific verb and resource ("Create a NEW shipping label") plus the scope that distinguishes it: it clones the order and carrier contract/product from an existing label. This makes it recognizably different from CreateLabelForOrder, but no sibling is named explicitly, so it stops short of a 5.

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

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

"Works even when the order is already complete" implies when this tool is applicable versus a normal label creation, but the agent must infer the alternative (CreateLabelForOrder) and there is no explicit when-not guidance or stated prerequisite that the labelId must be a valid previous label.

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=false, destructiveHint=true and openWorldHint=true, so the safety profile is carried structurally; the description adds the useful clarification that status is not mutated. It does not address visibility of the reply to the customer, whether replies can be edited or removed, or permission requirements, which matters given a destructiveHint of true.

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 no waste, front-loading the action and immediately qualifying it with scope and side-effect behavior.

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

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

For a three-parameter, 100%-documented write tool with annotations covering the safety profile and no output schema, the description supplies the one piece of context the schema cannot: that the ticket status is unaffected.

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 three parameters (ticketId, message, intentId) are already documented in the schema. The description adds nothing parameter-specific and only hints at scoping; baseline 3 applies when the schema does the 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 ("Add a reply on a support ticket") plus a scope constraint ("in your scope") and a side-effect guarantee ("without changing its status"). It does not differentiate from the sibling UpdateTicket, which also touches tickets, so it stops short of a 5.

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

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

The "without changing its status" clause implies when to prefer this over a status-changing tool like UpdateTicket, but that routing is left to inference. There is no explicit statement of when to use this versus UpdateTicket or any prerequisite/eligibility condition.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful conceptual context about master definitions versus applied charges but does not mention pagination, rate limits, or return behavior. No contradiction with annotations.

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

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

Two short sentences with zero waste. The core search purpose is front-loaded, followed immediately by the key distinction from applied label charges.

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

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

For a read-only catalog search with full parameter documentation and no output schema, the description provides enough domain context to call the tool correctly. It could be slightly stronger by naming the partner-specific sibling tool or clarifying result ordering, but no critical information 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 are already documented in the input schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable given complete schema coverage and sets the baseline at 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?

States a specific verb and resource: searching the global carrier surcharge catalog. It also clarifies that these are master definitions rather than charges applied to labels, which meaningfully scopes the tool. It does not explicitly name sibling alternatives such as GetPartnerCarrierSurcharges, so it falls short of a 5.

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

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

The description implies usage by contrasting catalog definitions with label-applied charges, helping the agent understand the domain. However, it gives no explicit when-to-use guidance, no exclusions, and no named alternatives for partner-specific or applied surcharge lookups.

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=true, destructiveHint=false, openWorldHint=false), so the description's job is narrower. It still adds real context the annotations lack: results are summary rows only, bodies are excluded, filters combine with AND, and Admin/Superuser authorization is required. Only the pagination/return-shape behavior is left implicit.

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

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

Three short sentences with no filler. The core scope ('summary rows without bodies') is front-loaded, followed by filter semantics and the access prerequisite in descending order of importance.

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 10-parameter read-only search with no output schema, the definition covers the essentials: what is returned at a high level (summary rows, no bodies), how filters combine, and who may call it. What's missing is a concrete sense of the returned row fields and how pagination interacts with the 200-row cap, which matters given there is no output schema to consult.

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 each of the 10 parameters carries its own description (limit range, date formats, status enum, carrier by name or id, partial-match fields), so the schema does the heavy lifting. The description adds only one generic note that all filters are optional and AND-combined; it does not clarify semantics like intentId correlation or partial-match behavior beyond what the schema states.

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 (search/list) and resource (label log summary rows) plus a scoping qualifier ('without bodies') that separates it from a full-body log fetch. It never names the obvious sibling get_label_log, so an agent must infer the split from the 'without bodies' phrasing rather than being routed 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?

The description gives useful preconditions ('All filters are optional and combined with AND', 'Admin or Superuser access required'), which tells the agent how to build a query and whether it may call it at all. However, it offers no explicit when-to-use/when-not guidance and never names alternatives such as get_label_log, FindLabel, or SearchShippingLabels.

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, openWorldHint, and destructiveHint=false. The description adds useful behavioral context by noting the endpoint equivalence and explaining that the returned id is the ParcelShopId used for a pickup-point label, though it omits auth or rate-limit behavior.

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

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

Two short sentences carry the core purpose, data source, and key identifier mapping without filler. The most important information is front-loaded.

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

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

For a read-only search with no output schema, the description gives the core selection criteria, data-source equivalence, and the key return identifier. It does not describe the full returned record shape or search radius, but the schema and annotations cover most remaining needs.

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 country, city, postcode, carrier, intentId, and organisationId are already documented in the schema. The description does not add parameter-level meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description states a specific action and resource: finding pickup points near an address, with the data source named. It does not explicitly distinguish the tool from label-search or carrier-route siblings, but the purpose is clear enough to avoid confusion.

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 “pickup points near an address,” so an agent can infer this is for locating parcel shops before creating a pickup-point label. However, there is no explicit when-to-use guidance, no mention of alternatives, and no exclusions.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description still adds real behavior: tenant scoping consequences of omitting organisationId and a hard 200-row result cap, which the agent cannot infer from structured fields. It stops short of 5 because nothing is said about ordering or whether the cap implies truncation rather than pagination.

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

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

Three short sentences, front-loaded with the core scope and the endpoint equivalence, then permissions, then the cap. Every sentence carries information, though the POST /api/Labels/Search reference is of limited use to an agent that cannot read that spec.

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, all-optional tool with no output schema, the description covers scoping, permissions, and the result cap well, but says nothing about what a returned row contains or how results are ordered. An agent knows how to call it but not what it will get back.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding the semantic consequence of omitting organisationId for partners vs. subpartners, which the schema's "Required for staff" note does not fully spell out. The carrier/contract/date-range restatement is redundant with the schema and adds no syntax detail.

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 ("Search labels") and enumerates the filterable dimensions (carrier, contract, created range), plus names the equivalent REST endpoint. It does not explicitly distinguish itself from look-alike siblings such as FindLabel, ListRecentLabels, or GetLabelsForOrder, so it stops short of a 5.

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

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

The tenant scoping sentence (partners may omit organisationId, subpartners are limited to their companies) gives a real usage condition, but the description never states when to pick this over FindLabel / ListRecentLabels / search_label_logs. Usage is implied by the filter set rather than prescribed.

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 destructiveHint=true and openWorldHint=true, so the description only needs to add context. It does add that this hits an external service (PrintNode) and uses the default printer, but it never explains the destructive nature — e.g., that a re-send may produce a duplicate physical label or incur cost, and whether it can be undone.

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

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

A single, front-loaded sentence with no filler. The action, the target system, and the printer selection are all in the first clause set, and nothing is repeated from the title.

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

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

For a two-parameter tool with full schema coverage and annotations, the description covers the core action. It is still thin on outcome: no indication of what 'sent' means (queued vs printed), what happens if the label was cancelled or already printed, or how failures surface. No output schema exists to carry that burden.

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 already documented ('Label usage id', 'Optional correlation ID for an existing investigation'). The description only indirectly clarifies that labelId refers to an existing label via 'again', so baseline 3 applies. Nothing is added about whether intentId is needed for tracing.

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

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

The description gives a specific verb and resource ('Send a label print job to PrintNode') and adds two distinguishing details: it is a re-send ('again') and it targets the organisation default printer. This separates it from DownloadLabel or RemakeLabel, though the relationship to those siblings is never stated 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?

The word 'again' implies the label already exists and this re-triggers printing, which is implied usage guidance. However, there is no explicit statement of when to prefer this over RemakeLabel, DownloadLabel, or GetLabel, and no prerequisites (e.g., label must already be created or in a printable state) 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 declare the operation as read-only and non-destructive, so the description does not need to repeat that. It adds meaningful behavioral context beyond annotations: there is no row limit, and partner users are restricted to their own scope.

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

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

The definition is two efficient sentences with no wasted language. The purpose and the key scope restriction are front-loaded.

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

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

For a read-only aggregation tool with five fully documented optional parameters and no output schema, the description gives enough to call it correctly. It could more explicitly describe the aggregation output shape, but the core return semantics are stated.

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 five optional parameters are already well documented. The description adds a grouping notion (“by carrier and user”) but does not clarify parameter behavior beyond what the schema provides.

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

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

The description states a specific verb and output type: return aggregated shipment counts and totals by carrier and user. This clearly distinguishes it from list/search tools, though it does not explicitly differentiate it from overlapping siblings like PartnerSummary or GetAnalytics.

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

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

It provides a useful scope constraint — partners see only their own partner scope — but does not say when to use this tool versus alternatives such as PartnerSummary or GetAnalytics. Usage is implied by the aggregation purpose rather than explicitly guided.

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=false and destructiveHint=true, so the safety profile is covered. The description adds nothing about overwrite semantics, what happens to fields left null, or whether the update is reversible — the key behavioral questions for a destructive partial-update tool with six optional nullable params.

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

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

One front-loaded sentence with no filler; the updatable fields appear immediately. It is efficient, though the terseness borders on under-specification for a 7-parameter mutation.

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

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

For a destructive, seven-parameter mutation with no output schema and zero schema documentation, the description should explain the remaining parameters and the null/omitted-field behavior. It covers less than half the surface an agent needs to call this correctly.

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

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

Schema description coverage is 0% across 7 parameters, so the description must compensate and does not. It mentions only margin, amount, and contract price, leaving marginType, franchisePercentageMargin, intentId, and externalLedgerCode entirely 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?

The description names a specific verb (update) plus the resource (customer-specific rate) and the mutable fields, which distinguishes it from the sibling UpdatePartnerRate and pairs naturally with AddCustomRate. It is clear, though it does not explicitly call out the sibling contrast.

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?

"on an existing customer-specific rate" implies the prerequisite (a rate must already exist, so use AddCustomRate to create one), but there is no explicit when-to-use vs when-not guidance or reference to UpdatePartnerRate/AddCustomRate by 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 declare readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds almost nothing beyond that: it does not say whether this is a partial update, whether omitted fields are left untouched, or what side effects the destructive hint implies.

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

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

The single sentence is front-loaded and free of filler. It is appropriately brief, though its brevity contributes to the parameter and behavioral gaps rather than resolving them.

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

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

For a destructive mutation with seven parameters, zero schema descriptions, and no output schema, the description is too thin. It should at minimum clarify the partial-update semantics and identify the undocumented parameters.

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 carry parameter meaning, but it only names margin, amount, and contract price. Four parameters (marginType, franchisePercentageMargin, externalLedgerCode, intentId) are left completely undocumented 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?

The description states a specific verb (Update) and resource (partner rate) and bounds the target with '(no customer)', which helps separate it from customer-oriented rate tools. It does not name any sibling such as UpdateCustomRate or UpdatePartnerSurcharge, so differentiation is only partial.

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

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

There is no explicit guidance on when to choose this over UpdateCustomRate, UpdatePartnerSurcharge, or AddPartnerRate. The parenthetical '(no customer)' hints at scope but does not give the agent a decision rule or any preconditions for use.

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=false and destructiveHint=true, so the safety profile is covered by structured data. The description's 'amount, margin, VAT, or carrier cost' phrasing hints at a partial/selective update rather than full replacement, which is useful, but it never resolves the critical ambiguity that every optional field defaults to null — whether omitting a field leaves it unchanged or clears it is unstated for a destructive 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 sentence with no filler, and the verb plus resource lead immediately. It is efficient, though so compact that it carries no supporting context about update semantics.

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

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

For a destructive 7-parameter mutation with no output schema, the description omits partial-vs-full update semantics, null handling, and any permission or reversibility note, and gives no guidance for distinguishing it from UpdatePartnerRate. The schema happens to be fully documented, but the behavioral contract an agent needs before writing 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 each of the 7 parameters is already documented, and the baseline for that case is 3. The description restates four of the fields (amount, margin, VAT, carrier cost) and omits useInPreInvoicing and intentId without adding any semantics the schema does not already carry.

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

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

The description pairs a specific verb ('Update') with a specific resource ('existing partner surcharge') and names the mutable fields (amount, margin, VAT, carrier cost), so the action is unambiguous. It does not, however, distinguish this tool from closely named siblings like UpdatePartnerRate, UpdateCustomRate, or AddPartnerSurcharge.

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?

'On an existing partner surcharge' weakly implies the record must already exist and a surchargeId is required, but there is no explicit when-to-use, no when-not-to-use, and no routing to UpdatePartnerRate or UpdateCustomRate, which sit in the same sibling cluster. The agent must infer tool selection purely from the 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 declare the destructive mutation profile (readOnlyHint=false, destructiveHint=true), and the description is consistent with that. It adds the valid status names but does not add permissions, reversibility, or side-effect details 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?

Two sentences, front-loaded with the action and followed by the valid status names. There is no redundant or wasted text.

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

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

For a simple status-update mutation with rich annotations and a fully described schema, the description supplies the key missing detail: allowed status values. It lacks explicit usage guidance, but the core calling information is complete and no output schema exists to explain.

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

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

Schema coverage is 100%, so baseline is 3; however, the description adds meaningful semantics by listing the exact valid status names, which the schema’s status property does not express as an enum. It does not explain intentId, but the schema does.

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: "Change a support ticket's status." The enumerated status names further pin down the operation, and no sibling tool performs ticket status changes (ReplyToTicket handles replies instead).

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

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

The purpose implies the tool is used when a ticket status needs changing, but there is no explicit guidance on when to use it versus ReplyToTicket or when not to use it. Usage is inferable rather than stated.

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