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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is covered elsewhere; the description adds the non-obvious consequence that rates are refetched and prices/estimated delivery can change. It does not mention whether labels are repriced or re-bought, which is the one remaining behavioral gap.

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

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

Front-loaded with the operation and effect, then constraints; three short sentences with essentially no filler. The 'ship date on Pirate Ship's buy page' framing is slightly indirect but still earns its place as domain 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?

No output schema exists, and the description covers the return ('new rates'), the mutation's side effects, and the draft-only precondition. What is missing is minor: behavior on failure or on a batch that has already purchased labels.

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

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

With 50% schema description coverage, the schema documents ship_date but not batch_id; the description compensates partly by implying batch_id must be a draft batch and by restating the ship_dates constraint. It adds marginal meaning beyond the schema rather than full compensation for the undocumented 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+resource ('Moves a draft batch to another ship date') plus the side effect ('returns its new rates'), and constrains scope to drafts. An agent can distinguish this from create_batch, get_batch, or rename_batch without opening a schema.

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

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

'Works on drafts only' gives an explicit precondition, and 'Pick a date from a rate's ship_dates' tells the agent where valid values come from. It stops short of naming alternatives (e.g. re-creating a batch for non-draft changes), so it is clear context rather than full when/when-not routing.

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

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

Adds real behavior beyond annotations: nothing is charged, the batch is a draft, Pirate Ship splits it into rate groups (domestic small/big/heavy/international), and unratable rows are counted in errors rather than failing the call. Annotations already cover the safety profile (destructiveHint=false, openWorldHint=true), so this is strong supplementary context; omitted are duplicate-handling/concurrency and the response shape.

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

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

Three dense sentences, front-loaded with the core purpose and the follow-up call, then the inheritance/override rule, then caveats. Every clause carries information, though the third sentence packs errors/get_batch/delete_batch tightly enough to read as a run-on.

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 11-parameter creation tool with no output schema and 36% coverage, the description supplies the missing workflow context (create → buy_label → get_batch/delete_batch) and implies the return contains rate groups and an errors count. It does not state what identifier comes back to use with get_batch/buy_label, which is the one remaining gap an agent must guess at.

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

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

With only 36% schema coverage, the description carries the load and does so for the hardest part: the package (packaging, weight_oz, size, or package_preset_id) applies to every shipment while a recipient's own weight_oz or size overrides it, and the 500-recipient cap. It says nothing about signature, insured_value_usd, or the per-row extras like rubber_stamp_1, leaving several parameters documented only by their bare types.

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 opening sentence states a specific verb and resource ('Unpaid draft batch for many packages') plus the creating-mechanism ('Pirate Ship's spreadsheet upload'), which lets an agent separate it from the order-driven sibling create_batch_from_orders without opening the schema. It stops short of naming that sibling explicitly, so differentiation is inferred 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?

Gives a clear lifecycle: create the draft, buy it with buy_label (one rate_id per rate group), inspect failures with get_batch, discard with delete_batch. It communicates the context (many packages from your ship-from address) but offers no explicit 'use this instead of create_batch_from_orders when...' exclusion.

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

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

Adds real context beyond the annotations: the batch is rated but not paid, no label is purchased, and large batches are built asynchronously with progress reported in the answer. That async behavior is not derivable from readOnlyHint=false / idempotentHint=false, and it materially affects how the agent should interpret the response. It stops short of saying what happens to unratable orders or how repeated calls behave.

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

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

The core fact is front-loaded in one line, and the second paragraph elaborates usefully. Slight redundancy — 'nothing is bought' and 'no label is bought' say the same thing twice — but 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 five-parameter creation tool with full schema coverage and no output schema, the description covers the essentials: what feeds the batch, that it is rated only, that nothing is charged, and that large batches return before completion with progress in the answer. An agent can call this correctly without further reading.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: recipient data comes from the orders while size and weight come from the saved package — the coupling between order_ids and package_id that the schema does not state. It leaves ship_from_id, title and override_multiple entirely to the schema, which is acceptable given full coverage.

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

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

The first sentence names a specific verb and resource — turning store orders into a batch of shipments — plus the key constraint of a single saved package, so the agent knows exactly what is produced. It implicitly separates itself from create_batch and create_shipment by 'from imported orders' and 'batch of shipments', but never names those siblings explicitly.

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

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

Usage is implied: it is the tool for orders already imported (schema even points to list_import_orders). 'Nothing is bought / no label is bought' steers the agent away from expecting labels, but there is no explicit when-to-use versus create_batch or when-to-ship versus create_shipment guidance.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds non-obvious value by explaining the deferred effect ('Nothing is sent now: Pirate Ship uses the template when a label is bought with tracking emails on'), which clarifies the side-effect timing. Duplicate-name handling and permission requirements remain unstated.

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

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

Front-loaded with the core action, and every sentence carries real information about behavior. It is slightly redundant – 'Adds a tracking email template' and 'Saves a new tracking email template' restate each other, and the placeholder list repeats the schema verbatim.

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

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

With no output schema, the description must carry the return-value burden, and it never says what comes back (e.g., the created template's id) or how the call fails. The side-effect timing is well covered for a mutation tool, but duplicate-name behavior and the response shape are gaps an agent will notice.

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 71% and the description's placeholder list duplicates what html already documents in the schema, so most of the semantic load is already structural. Adding a 4 would overstate the contribution; a 3 understates it, because the placeholder enumeration does at least reinforce the one field an agent is most likely to get wrong. Score sits between, at 4 for reinforcing the highest-risk 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 (adds/saves) and a precisely scoped resource (a tracking email template used for tracking-link emails), and even clarifies what it does not do (send anything now). An agent can distinguish it from update_email_template, delete_email_template, and list_email_templates without opening any schema.

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

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

Gives real usage context – the template is consumed when a label is purchased with tracking emails enabled, and nothing is sent at creation time. But it never says when to prefer this over update_email_template, what happens if a template with the same name exists, or whether prerequisites (e.g., tracking emails enabled) are required.

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 mutation plus non-idempotent/openWorld, so the description adds real value on top: which packaging types require length_in/width_in/height_in, that flat-rate needs none, and that weight_oz 0 defers weight to each label. It does not say what happens on duplicate titles or whether the new package 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?

Three short sentences, front-loaded with the core action and followed by the constraints an agent actually trips over. The parenthetical field list is mildly redundant but nothing is wasted.

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

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

For a 13-parameter mutation with no output schema, the description covers the highest-risk ambiguity (which dimensions each packaging type demands) and the weight_oz=0 escape hatch. Remaining gaps are secondary optional flags rather than call-blocking unknowns.

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

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

Schema coverage is only 38% and several params (length_in, width_in, height_in, irregular, packaging, signature, insured_value_usd, hazardous_materials) carry no schema description. The text compensates well for the dimension and packaging params but leaves signature, insurance and hazardous-materials semantics 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?

States a specific verb+resource (creates a Saved Package) plus the payload it stores (type, size, weight, extra services) and where it appears in Settings. That distinguishes it from create_shipment and from the update/delete/list saved-package siblings, 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 conditional dimension rules imply when a given packaging choice is valid, and 'for reuse on labels' hints at the create-a-template-vs-one-off scenario. However it never says when to call this instead of update_saved_package or instead of passing dimensions directly to create_shipment, and no prerequisites 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?

Annotations declare it is a non-read-only, non-idempotent, non-destructive write. The description adds real context beyond that: it consumes only labels that have no form yet (so repeat calls have less to work with), it returns a PDF link, and it errors when nothing is eligible. It stops short of saying whether an existing form can be regenerated or what the error payload looks like.

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

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

Front-loaded: the first line gives the resource and the return value, then a sentence explains what gets put on the form and why the carrier benefits. The rationale sentence ('The carrier scans that one sheet instead of every package') is useful but slightly padded, so not a full 5.

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-optional-parameter creation tool with no output schema, the description covers the return value (PDF link), the selection semantics, and the error condition. Defaults and per-parameter meaning live in the schema, so nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters (including defaults for ship_date and from_address_id) are already documented inline. The description only reinforces the either/or grouping of 'one Ship Date and Ship From Address (or of one batch)' without adding format or precedence detail beyond the schema's 'ignores ship_date' note, 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 (create) and resource (USPS End of Day SCAN Form) and defines its scope: the labels of one Ship Date / Ship From Address, or of one batch. The output form (a PDF link) is named, so an agent can tell this apart from list_scan_forms or download_labels 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?

Explains the when: labels of one Ship Date plus Ship From Address, or one batch, that currently have no SCAN Form. It also names the prerequisite failure mode ('No labels without a form: Pirate Ship answers with an error'). It does not point at a sibling to use instead when no eligible labels exist, which keeps it short of a 5.

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

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

Adds genuinely useful behavior beyond the annotations: US-only scope, that Pirate Ship normalizes and completes ZIP+4, that the new address is not made default, and that omitting return_address routes returns to the origin. It does not warn about duplicate creation, given idempotentHint=false, nor about the failure mode for invalid or non-US addresses, which leaves a gap for a mutation tool.

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

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

Four short sentences, front-loaded with the action and followed by the two decision-relevant behaviors (return address fallback, ZIP+4 normalization) and the routing hint. Minor waste in the near-duplicate opening pair "Adds a US Ship From Address" and "Saves a new Ship From Address in Pirate Ship."

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, an agent still learns the essential semantics of a create call: what entity is persisted, how the return address falls back, ZIP+4 normalization, and that defaults are untouched. Still missing is what the call returns (e.g., an identifier for later update/delete calls) and error behavior for non-US or invalid addresses.

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 67%, and the description's return_address default restates what the schema already documents ("Where returns go. Default: the origin."). Several nested origin fields (zip, city, phone, company, full_name) carry no description in either place, and the description adds no format or validation guidance beyond the schema's maxLength/minLength constraints, so it only marginally compensates.

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 ("Adds a US Ship From Address") plus scope (US-only, optional distinct return address), which clearly separates it from update_ship_from_address, list_ship_from_addresses, and set_default_ship_from_address among the siblings. An agent can identify the operation without opening the schema.

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

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

Explicitly routes the agent away from this tool for the default-address case: "It does not become the default: call set_default_ship_from_address for that." It also implies when to supply return_address. It stops short of naming exclusions against update_ship_from_address (editing an existing address) or what to do when the address already exists.

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

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

Annotations only mark this as a non-read-only, non-destructive, open-world, non-idempotent call; the description adds the material economics ('Nothing is charged'), the draft-object lifecycle (buy_label / delete_batch), and a non-obvious edge case where the call returns status address_correction and no draft at all. It stops short of warning that each call produces a new draft batch, which matters for the declared idempotentHint=false.

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

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

Front-loaded with the core identity ('Unpaid draft label... buy it with buy_label') and then fills in the rate payload, packaging alternatives and the correction branch. Dense but every sentence carries distinct information; the 'Pirate Ship's Single Shipment form up to Get Rates' framing is slightly wordy but earns its place by anchoring the workflow.

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 13-parameter mutation with a nested recipient object, no output schema and 38% schema coverage, the description covers the happy path and the address-correction detour well but says nothing about the shape of the returned rate list or how the remaining optional parameters (signature, insurance, rubber stamps) affect the draft. Adequate to call correctly, not complete.

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

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

Schema description coverage is only 38% across 13 parameters, and the description compensates for some of it: it explains the packaging/weight_oz/size alternative to package_preset_id, the ship-from default, and the address_correction semantics. But signature, insured_value_usd, rubber_stamp_1/2, the length/width/height relationship, and the nested `to` fields are left entirely to an under-documented schema.

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

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

The first sentence gives a specific verb+resource+state ('Unpaid draft label for one package with every rate') and immediately names the follow-up tool (buy_label). The second sentence pins it to a concrete workflow ('Single Shipment form up to Get Rates') and states what comes back (USPS/UPS services with your price, retail price, delivery estimate, ship dates). An agent can separate this from get_rates, buy_label and delete_batch without opening any schema.

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

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

Explicitly states when this tool is the right one ('up to Get Rates'), what it does not do ('Nothing is charged'), and which siblings handle the next steps ('buy_label buys one of the rates, delete_batch drops the draft'). It also spells out the address-correction branch: call with ask to get a suggestion, then re-call with accept or skip. That is a full when/when-not/alternatives map.

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 destructive=true and idempotent=false, and the description adds genuinely new behavior: deletion is gated on the draft being unpaid, and bought labels will not be removed. It stops short of saying what the agent sees when the gate fails (error vs silent no-op) or that a batch delete removes multiple items at once.

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, the operation and its scope up front, the alternative path second. Nothing redundant and nothing buried.

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

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

For a destructive one-parameter mutation with no output schema, the description covers the safety constraint and the escape hatch, which is the core need. Minor gaps remain around failure behavior and batch-level scope, but nothing an agent needs before invoking it correctly is missing.

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

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

Schema coverage is 0% and the single required batch_id is undocumented, but the description partly compensates by attributing the batch to create_shipment/create_batch, implying where a valid identifier comes from. It gives no hint about identifier format or that list_batches/get_batch can supply one, so it adds only marginal meaning.

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

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

States a specific verb and resource ("Deletes an unpaid draft batch") and ties the object back to its origin (create_shipment / create_batch), which separates it cleanly from refund_batch and the other siblings. The phrase "or single shipment" is a slight mismatch with a tool whose only parameter is batch_id, leaving a small ambiguity about whether shipment-level deletion is really supported by this call.

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

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

Explicitly defines the usable domain (unpaid drafts, anything not yet bought) and the excluded domain (bought labels cannot be deleted), then routes the agent to refund_label or refund_batch for that case. Both the when and the when-not, with named alternatives, are present.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds nothing beyond that: no statement that deletion is permanent, no indication of what happens to templates currently referenced by active tracking settings, and no error/permission 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?

One short, front-loaded sentence with no filler, but it is terse to the point of under-specification rather than genuinely efficient.

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, non-idempotent mutation with no output schema, the description says nothing about consequences, irreversibility, or failure modes. An agent knows what the tool touches but not what it risks.

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

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

Schema coverage is 100% and the single parameter is documented in-schema with a useful provenance note ('id from list_email_templates'). The description contributes no additional parameter meaning, 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 ('Removes') and resource ('tracking email template'), which cleanly separates it from create_email_template, update_email_template, and list_email_templates. It does not explicitly name those siblings, but the verb alone makes the distinction 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?

No guidance on when to delete a template versus when to update it, and no mention of alternatives. The only hint at preconditions lives in the schema ('id from list_email_templates'), not the description.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful consequence — that existing labels made with the package survive — but says nothing about irreversibility, permissions, or what happens to shipments referencing the package.

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

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

Two short sentences with no filler, and the primary action is front-loaded ahead of the side-effect caveat. It could name the alternative or prerequisite in the same space, but nothing is wasted.

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

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

For a one-parameter delete with full schema coverage, no output schema, and annotations covering the destructive/non-idempotent profile, this is nearly complete. The only real omission is confirmation or irreversibility guidance.

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

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

Schema description coverage is 100% and the single parameter package_id is already documented as 'id from list_saved_packages.' The description adds no further meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (removes) and resource (Saved Package), which is unambiguous and distinct from siblings like create_saved_package, update_saved_package, and list_saved_packages. It does not explicitly name those siblings, but the verb makes the distinction obvious.

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?

Deletion intent is implied by 'Removes', but there is no explicit when-to-use framing, no mention of when to use update_saved_package instead, and no prerequisites such as confirming the package is unused. 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 flag destructive=true, but the description adds genuinely new consequences: existing purchased labels are unaffected, at least one address is always retained, and the default is never deleted. These are exactly the side-effect and precondition details an agent needs beyond the hints.

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

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

The prohibition on deleting the default is front-loaded correctly, and the four short sentences are easy to scan. There is mild redundancy, since 'the default address cannot be removed' is restated later as 'never deletes the default'.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the description covers the important constraints and the blast radius. It doesn't say what a failed delete returns (e.g., invalid or default id), which is a minor remaining gap.

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

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

Only one parameter and the schema already documents it at 100% coverage, including the pointer to list_ship_from_addresses. The description adds no syntax or format detail beyond that, 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?

States a specific verb and resource ('Removes a saved Ship From Address') and scopes it to Settings, which cleanly separates it from create/update/list_ship_from_addresses and set_default_ship_from_address. An agent can identify the operation without opening the schema.

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

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

Gives an explicit precondition/exclusion: the default address cannot be removed and another address must be made default first, which implicitly routes to set_default_ship_from_address. It doesn't name that sibling tool explicitly, keeping it short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: building takes a few seconds, labels use the account's configured size/format, and refunded or later-printing return labels are excluded. That exclusion rule is information an agent could not infer from annotations.

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

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

The lead sentence delivers the core purpose immediately, followed by two short supporting sentences on mechanics and exclusions. Slight redundancy in restating 'Pirate Ship's Print Labels' and the tool title, but no filler beyond that.

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 properly explains what is returned (a link to a generated file), plus latency and exclusion rules. The remaining gap is the unaddressed empty-required-parameters situation: it never says at least one of batch_id or shipment_ids must be provided, nor how size limits affect behavior.

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

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

Schema coverage is only 50% — shipment_ids has no inline description — so the description carries extra burden. It partially compensates by pairing batch_id with 'every printable label of this batch' and contrasting it against 'chosen shipments', but it does not clarify the either/or exclusivity, the 100-item cap, or what happens when no parameter is supplied.

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

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

The first sentence gives a specific verb (download / build a file) and resource (printable labels), and scopes it to either a batch or chosen shipments. This clearly distinguishes it from sibling tools like get_batch, list_batches, and create_batch, which manage batch metadata rather than produce label files.

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

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

The description implies the selection model (batch_id OR shipment_ids) but never states when to prefer one over the other, nor names any alternative tool for related tasks. Usage is hinted at ('of a batch or of chosen shipments') 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 carry readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: it returns a link to a CSV, and when no rows match it returns empty=true with no link — a non-obvious outcome the agent would otherwise be surprised by.

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 no-results behavior and the sibling exclusion are front-loaded where an agent will read them. Slightly wasteful: the opening sentence is a sentence fragment and the 'every column of the matching list_ tool' clause is dense, but overall tight.

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

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

With no output schema, the description does the work of explaining the return contract (a link, or empty=true and no link). That plus the date/search scoping makes it callable with confidence; only the sort param and column-set details are left implicit.

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

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

Schema description coverage is 60%; search and both dates are documented in the schema, and the report enum is self-describing. The description adds framing (optional date range and search, columns mirror the list_ tool) but does not explain 'sort' or how report choice maps to available columns beyond a one-line mirror statement — baseline 3 for partially documented params.

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 (export/builds a CSV) and the exact resources covered (transactions, refunds, receipts, return labels, carrier adjustments), and explicitly routes shipments to export_shipments. An agent can distinguish this from the list_* siblings and from export_shipments without opening the schema.

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

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

'Shipments have their own tool, export_shipments' names an explicit alternative and exclusion. It also positions itself against the matching list_ tool ('same spreadsheet as the Export button... every column of the matching list_ tool'), giving clear context, though it does not say when to prefer list_* over exporting.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real behavioral value on top: the return contract (a link), the empty-result behavior (empty true and no link), and the latency warning that large exports can take up to a minute. Those are exactly the traits an agent needs before committing to the 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?

Front-loaded with the output artifact, then column composition, then filter semantics, then edge cases and latency. Every sentence carries information; nothing is restated from the schema or annotations.

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 compensates fully by describing the return shape (link or empty), the failure/degenerate case, and the timeout expectation. Combined with 88% schema coverage for the 8 optional filters, an agent has everything needed 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 coverage is 88%, so the baseline is 3; the description earns an extra point by declaring that the entire filter set is inherited from list_shipments, which tells the agent the parameters behave identically to a sibling tool rather than being export-specific. It still does not add format hints for sort or date handling beyond what the schema documents.

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 (export), a specific artifact (CSV of the shipments report with every column) and the delivery form (download link). It anchors the tool to a known UI surface (Export button of Reports, Shipments) and enumerates the columns, so an agent can tell it apart from list_shipments and export_report without opening a schema.

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

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

"Takes the filters of list_shipments" gives clear context for when this is the right call (same filtering, file output instead of a JSON list). It does not explicitly say when to prefer list_shipments or export_report instead, so the exclusion side is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: USD denomination, the meaning of balance_settled_usd excluding still-settling payments, pending counts, and the 30-day reporting window. It does not discuss auth or rate limits, but for a read-only aggregate with rich annotations this 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?

The description is appropriately sized for a zero-parameter report tool and front-loads the core scope. The first sentence is a fragment and 'Reports page' appears twice, but the second sentence efficiently enumerates the returned data without obvious 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 needs to explain what comes back, and it does: balance, saved payment method count, pending refunds/returns, and last-30-day label count/total/average/payments. It also clarifies the settling caveat on balance_settled_usd. It could be more precise about return field names and structure, but it is complete enough for an agent to understand the tool's output.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description appropriately does not invent any.

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 a specific aggregate read: account balance, pending refunds/returns, saved payment methods, and last-30-day label metrics from the Reports page. It is not a bare restatement of the name, though it is phrased as a noun list rather than a clear action. It broadly distinguishes itself from list-oriented siblings by describing a combined Reports-page summary, but does not explicitly name 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 'from the Reports page' and by the aggregate nature of the returned data. However, the description does not state when to use this tool instead of siblings such as list_refunds, list_return_labels, list_transactions, or get_shipping_stats. No explicit exclusions or routing guidance are provided.

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

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

Annotations already establish readOnly, idempotent, non-destructive. The description adds genuine state-dependent behavior beyond that: a Rated draft lists all qualifying rates with rate_id, while a Billed batch reports per-shipment status, tracking, print/refund eligibility and amount paid per service. It stops short of noting any auth or rate-limit considerations.

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 subject before the exposition. Dense but every clause carries information; the long second sentence is justified by the distinct draft vs bought payload differences.

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 bears full responsibility for describing return values — and it does so thoroughly for both states, including the fields an agent would need to act on (rate_id, tracking, print/refund flags). Nothing essential to calling or interpreting the result 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?

Only one parameter with 100% schema description coverage, so the schema already carries batch_id's origin ('From create_shipment or list_batches'). The description adds no further semantics about the identifier, so baseline 3 applies.

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

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

States a specific resource (a single Pirate Ship batch) and enumerates its contents, distinguishing draft (Rated) from bought (Billed) states. It does not name a sibling like list_batches as the contrasting alternative, which keeps it just short of a 5.

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

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

Usage is implied rather than stated: 'rates to buy' with rate_id points forward to buy_label, and the schema notes batch_id comes from create_shipment or list_batches. There is no explicit when-to-use-this-vs-list_batches guidance or exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. Beyond that, the description discloses the concrete data returned—the six setting categories—which is valuable because there is no output schema, though it does not describe response shape or auth requirements.

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

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

The description is front-loaded, but the first line is a shorthand list that the second sentence repeats in expanded form: size/file format, packing list, logo, QR codes, address correction, and export format. It is not excessively long, but the duplication costs efficiency.

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

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

For a zero-parameter read-only settings getter with rich annotations, the description covers the settings returned and makes the tool callable. Only a formal response shape is absent, which is not critical without 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?

There are zero parameters, so there are no parameter semantics to explain. The schema already establishes this, and the description correctly does not invent parameters.

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 enumerates the exact settings returned (label size/file format, packing list, logo, QR codes, address correction, export format) and situates them under 'Settings, General', so the resource is unambiguous. It does not explicitly contrast with the sibling update_label_settings, so it stops short of 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?

No sentence says when to call this instead of update_label_settings or any other sibling. The field list only implies it is a read of general settings, with no prerequisites, exclusions, or alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's job is to add context - and 'Nothing is booked' plus 'surcharges are listed apart' tell the agent what the call does and does not commit to, and that the response separates base price from surcharges. It stops short of saying how surcharges are returned or whether quotes expire.

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 lead sentence is front-loaded and the carrier conditions come after, which is the right order, but the second paragraph repeats the first almost verbatim ('Nothing is booked' / 'without booking it'; 'USPS pickups are free' / 'USPS collects for free'). Roughly a third of the text is 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?

For a 10-parameter, read-only, no-output-schema tool the description covers the decisions that matter: no booking occurs, USPS is free and next-day, UPS requires a date and a pickup window, and surcharges are reported separately. The main residual gap is the shape of the returned price/surcharge data, which the description only gestures at.

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?

At 60% schema description coverage the schema already explains the carrier-conditional fields (date, ready_time, close_time, overweight all marked 'UPS only'), and the description largely restates that dependency. It adds genuine meaning for carrier choice - USPS is free and arrives next delivery day, so those parameters go unused - but package_count, total_weight_oz, location and instructions get no description-level treatment beyond the schema.

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

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

The opening sentence names a specific resource (a USPS or UPS pickup) and a specific operation (what it would cost), and immediately rules out the adjacent action with 'Nothing is booked.' That scope plus the free-USPS vs. paid-UPS split lets an agent separate it from list_pickups and from any booking flow 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?

'Prices one pickup without booking it' and 'Nothing is booked' clearly establish this as a quoting step, and the UPS prerequisites (date, ready and close time) tell the agent what must be supplied to get a valid quote. It never names a sibling as the alternative for the booking step, so the when-not-to-use half 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: which fields come back (your price, retail price, zone, estimated delivery), the cheapest-first ordering, that services unable to carry the package are excluded, and that no purchase occurs. It doesn't mention rate staleness, caching, or error conditions when no ship-from exists.

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

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

Front-loaded with the one-line essence before the detail paragraph, and every sentence conveys a distinct fact (units, dimension rules, filtering, no purchase). A few clauses are packed together densely, but there is no filler.

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

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

With no output schema, the description steps in to describe the returned fields and their ordering, and it covers the conditional parameter requirements and unit conventions for an 8-parameter tool. An agent has enough to call it correctly and interpret the results without further documentation.

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

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

Schema description coverage is only 50%, so the description carries useful weight: it ties packaging values to their required dimensions ('Parcel, SoftEnvelope and Irregular need length_in and width_in, a box also height_in'), notes flat-rate packaging needs only weight, and clarifies the ounce unit with a conversion example. It doesn't explain residential or to_country behavior, so it stops short of full compensation.

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

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

Names a specific action and resource: a rate quote ('Pirate Ship's Quick Rate Quote') for USPS and UPS services for one package, sorted cheapest first, and closes with 'Nothing is bought' to separate it from the shipment-creation siblings. It's clearly distinguishable from create_shipment and get_pickup_quote without opening the schema, though it never names an alternative tool.

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: rate quoting is the pre-purchase step, and 'Nothing is bought' signals it's safe to call repeatedly. But there is no explicit when-to-use or when-not, no mention of prerequisites like a configured default ship-from address, and no pointer to a sibling such as get_pickup_quote or create_shipment.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by enumerating the returned payload: title, status, USD totals and refunded amount, billing address, before/after balance, every covered transaction with batch_id and shipment_id, and reversals such as chargebacks.

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 resource definition, and the second sentence is a dense but purposeful enumeration of the receipt's fields. Slightly long but nearly every clause carries information the 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?

There is no output schema, so the description must carry the return-value burden, and it does: an agent knows precisely which fields come back for a receipt and how transactions relate to batches and shipments. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100% and the single parameter is documented in-schema as coming from list_receipts, so the description's repetition of that origin adds nothing new. Baseline 3 applies when the schema does all 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+resource ('one payment to Pirate Ship') and defines exactly what a receipt contains, then explicitly positions it as 'the receipt page of one payment from list_receipts', which separates it from the list sibling without requiring schema inspection.

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 'of one payment from list_receipts' tells the agent this is the detail view and where the identifier originates, giving clear usage context. It stops short of explicit when-not guidance or naming alternatives for related data like list_transactions or list_refunds.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the bar is lower, and the description still adds real value: costs are in US dollars, adjustments include the carrier-corrected weight/size with price delta and dispute state, and it discloses print/refund eligibility flags. It does not cover pagination or partial-failure behavior, but for a read-only fetch that is minor.

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 one-line summary is front-loaded ahead of the field inventory, which is appropriate given there is no output schema. The second sentence is long but each listed field earns its place as the only documentation of the return payload; no filler.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: status, carrier/service/zone, tracking, recipient, package, cost breakdown with surcharges and insurance, estimated delivery, originating order, print/refund capability, and carrier adjustments. An agent knows what it will get without opening anything else.

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 shipment_id and the optional batch_id are already documented in the schema (including batch_id's 'saves one request when known' purpose). The description adds no parameter syntax or constraints beyond that, 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?

Opens with a specific verb-and-resource statement (one shipment with tracking, service, cost, recipient, carrier adjustments) and the second sentence enumerates exactly what the single record contains. It implicitly contrasts with list_shipments by saying 'One shipment', though it never names the sibling explicitly.

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

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

Usage is only implied: fetch a single shipment by id. There is no statement of when to prefer this over list_shipments or get_batch, and no prerequisites; the only routing hint lives in the shipment_id schema text ('From get_batch or list_shipments'), not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds real behavioral context: the 30-day default, the one-year ceiling, and the USD denomination of all money values. It does not describe response shape or size, which keeps it at 4 rather than 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?

The opening clause front-loads what the tool returns and the date-range scope before the metric enumeration. The long list of charts is dense but each item earns its place as return-value specification given there is no output schema; only the 'as on Reports' phrasing is slightly redundant with the second sentence.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly: metric families, currency, default window, and maximum span. What is missing is the response structure and whether the data is grouped or flat, a moderate gap for a report-style tool.

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

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

Schema coverage is 100% and both date parameters are documented with format and defaults, so baseline would be 3. The description adds the one-year maximum span, a constraint absent from the schema, plus the default window, which is meaningful guidance for setting the range.

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 (a Reports-style aggregate over labels, spend, savings, tracking and destinations) and scopes it to a date range, which is materially different from the list_* siblings that return individual records. It never names an alternative explicitly, but the enumerated metric set makes the aggregate nature unmistakable.

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

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

It gives the operating envelope (default last 30 days, at most a year) and anchors the tool to 'as on Reports', which implies when it is appropriate. It does not say when to prefer this over export_report, list_transactions or list_carrier_adjustments, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds semantic meaning for each returned field (e.g. 'delay: when it goes out after the label is bought'), which is genuinely useful context. It says nothing about scope (account-wide vs. per-store) or error behavior, so it stops short of rich behavioral disclosure.

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

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

It is short and has no filler, but it is not front-loaded: the opening sentence is a fragment that reads like a continuation, and the reader must reach the field list to understand this is a settings read. 'delay_label as Pirate Ship shows it' is internal jargon that costs a sentence without adding much precision.

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 documenting the four returned fields (enabled, delay, branding, default_template_id) is exactly the right compensation and is largely present. Missing only the shape (a single settings object) and the scope of the settings (account-level?). Given zero parameters and full annotation coverage, this is close to complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The field explanations it does provide describe return values rather than inputs, which is appropriate for a no-arg getter.

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 never states a verb or framing like 'Returns the account's default tracking-email settings'; it opens with a sentence fragment describing the subject matter. The field list (enabled, delay, branding, default_template_id) does imply a read of tracking-email configuration, so purpose is inferable but not stated. It is distinguishable from update_tracking_email_settings only by the tool name, not the text.

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 versus update_tracking_email_settings (the obvious mutation counterpart) or list_email_templates, even though the description mentions templates. The only routing hint is that default_template_id comes 'from list_email_templates', which is a reference, not a usage rule. No preconditions or exclusions are given.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent; the description adds the essential behavioral facts: orders are moved rather than deleted, no shipment is created, and the action is reversible via unignore_orders. It doesn't cover edge behavior such as already-ignored or invalid ids, which matters given idempotentHint=false.

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

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

Two tight sentences with the core action front-loaded and the follow-up routing appended. Every clause carries information; 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 single-parameter reversible mutation with no output schema, the definition covers what it does, where orders go, and how to reverse it. The remaining gap is response/error behavior — whether a confirmation or count is returned and how invalid ids are handled — which an agent would otherwise have to discover by calling.

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 order_ids property already explains its source (list_import_orders). The description adds nothing about batch semantics — the 500-item cap, partial-failure behavior, or what happens with ids already ignored — so it sits at the baseline.

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: "Hides store orders from the Import list without shipping them." It also distinguishes itself from the two most confusable siblings by naming list_import_orders (for viewing) and unignore_orders (for reversal).

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

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

Gives clear operating context — use this to remove orders from the Import list without creating shipments — and names the sibling used to view the result and the sibling used to undo. It stops short of explicit when-not guidance (e.g. when to delete vs ignore), so not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is lighter; it adds real behavioral detail such as pagination termination semantics and the exact per-item fields returned (status text, first shipment's tracking number, per-status counts). One blemish: the opening 'and single labels' is never explained and slightly conflicts with the body, which describes only batches.

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

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

Front-loaded with purpose and ordering, then details, then the sibling pointer — a sensible order. There is mild redundancy: 'newest first' appears in both the first clause and again in 'The batches on Pirate Ship's Ship page, newest first'.

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

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

With no output schema, the description carries the burden of explaining return shape and does so thoroughly (counts, statuses, tracking number, per-status tallies). The only incompleteness is the unexplained 'single labels' phrase, which leaves ambiguity about whether non-batch labels can appear.

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 already says '0 is the newest page', but the description adds the meaning that an empty list signals exhaustion, which the schema cannot express. Only one parameter exists, so there is little more to say.

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

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

States a specific verb+resource (list batches) plus scope and ordering (newest first, status and tracking counts). It also names get_batch as the single-item counterpart, so an agent can distinguish it from the sibling without opening a schema.

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

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

The final sentence routes detailed single-batch lookups to get_batch, and the 'empty list means no more pages' note tells the agent when to stop paging. It lacks an explicit 'use this when you need an overview rather than counts/stats' exclusion, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value by disclosing what each record contains (old vs actual measurement, old vs new cost, USD adjustment, dispute status) and by pointing to the dispute path, though it says nothing about result volume or ordering 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 lead sentence is a fragment ('with old and actual package') and the second is a dense run-on that restates the old/actual idea twice (values and costs). The content is mostly substantive, but the phrasing costs readability without adding precision.

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

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

With no output schema, the description does the work of explaining what a returned adjustment looks like, which is the most important gap it could fill for a read-only list tool. What remains missing is pagination/return-shape behavior and filter semantics, both of which an agent must open the schema to learn.

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?

Eight parameters and only 63% schema description coverage, yet the description explains none of them — no mention of sort, limit, offset, status, carrier arrays, or the from_date/to_date semantics. The field list (weight, size, package type, zone, ZIP, costs, dispute flag) describes record contents, not filter inputs, so it does not compensate for the schema gap.

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

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

The description defines the resource concretely: extra charges or credits a carrier applied after a label was used, arising from measurement discrepancies. That is far more than a restatement of the name and lets an agent distinguish it from list_refunds or list_transactions, though it never explicitly names those siblings.

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 use case (carrier re-measured weight/size/package type/zone/ZIP versus the label) but never states when to call this versus other listing tools or report exports. The one routing cue is a follow-up action: 'dispute_adjustment disputes one by shipment_id,' which tells the agent where to go after listing, not whether to list now.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real semantic context beyond that: the field inventory, the [Tracking #] placeholder convention in the HTML body, and the meaning of the 'default' marker as the template applied to new labels. It says nothing about ordering or pagination, but with a zero-parameter collection endpoint that is a minor omission.

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 first line ('subject, sender, HTML body; one is the default') is essentially restated by the second line's fuller field list, so roughly a sentence of the two is redundant. The content is front-loaded and bounded, but the duplication costs it.

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, and it does so by enumerating name, subject, sender name, reply-to email, BCC address, HTML body and the default flag. For a no-parameter list tool with full annotation coverage this is close to complete; only ordering/paging behavior is unaddressed.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description instead spends its words on the returned shape, which is the right allocation 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?

The description names the resource precisely (the tracking email templates Pirate Ship sends to label recipients) and enumerates the fields each record carries, so the agent knows exactly what it gets back. It never states the verb 'list' outright — that comes only from the title — and it doesn't distinguish itself from siblings like get_tracking_email_settings or create_email_template, so it is clear but not sibling-differentiating.

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 framing ('templates ... used for new labels'), which tells the agent these are the records backing tracking-email configuration. There is no explicit when-to-use statement, no exclusion, and no pointer to create_email_template / update_email_template / delete_email_template as alternatives for the mutation paths.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing freshness dependency on sync_store_orders and the shape of each returned row. It does not describe pagination behavior or how much data a page holds, leaving one gap.

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

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

Front-loaded with the core definition and dense with useful detail; every sentence carries information. It slips into sentence fragments ('ignored true lists the orders you hid...') that read slightly clipped, but nothing is filler.

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

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

With no output schema, the description correctly takes on return-shape duty by naming the grid columns. It omits default page size and total-count behavior, which matters for a paginated list, so it is strong but not fully complete.

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

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

At 50% schema coverage, limit and offset are undocumented in both the schema and the description. The text does add meaning for ignored ('lists the orders you hid with ignore_orders'), clarifying beyond the schema's 'Show the ignored orders instead,' but nothing explains search or paging semantics, so compensation is partial.

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

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

States a specific verb and resource with tight scope: unshipped orders from connected store integrations, 'one row per order with the grid's columns (order number, recipient, items, store).' That distinguishes it from list_shipments and list_batches by domain, though it never names a sibling it is not, 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?

Gives explicit workflow context: 'Run sync_store_orders first for the newest' and 'Use order ids in create_batch_from_orders,' plus the condition that ignored=true surfaces orders hidden by ignore_orders. It offers no exclusion ('don't use this when...'), so it reads as clear context without alternatives rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds substantive content context — the output is grouped per carrier and includes measurement requirements and Pirate Ship's maximum weight in ounces and side lengths in inches. It does not describe the return shape (flat list vs. carrier-keyed map), leaving a modest gap.

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

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

Two sentences, front-loaded with the core resource statement, and no filler. The second sentence is grammatically dense ('the packaging keys get_rates and saved packages take, per carrier, with which measurements each needs') and takes a second read, but every clause carries information.

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

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

With no output schema and no parameters, the description must carry the return-content burden, and it does: it names the fields (packaging type, size/weight limits, required measurements) and the units (ounces, inches). Only the concrete structure of the returned collection is unspecified, which is a minor omission for a reference-list tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Repeating the 'per carrier' scoping is consistent with the parameterless signature.

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 — packaging types per carrier (box, envelope, flat rate) plus their size/weight limits — so the agent knows exactly what reference data it returns. It also ties the output to the siblings that consume it (get_rates, saved packages), which helps separate it from list_saved_packages, though it never explicitly says 'this is not that tool'.

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 establishes clear context by naming what the keys feed into ('the packaging keys get_rates and saved packages take'), implying an agent should consult this before calling get_rates or create_saved_package. It stops short of an explicit when-to-use/when-not-to-use instruction, but the consumer linkage is strong enough to guide 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered; the description adds real signal beyond that by enumerating what comes back, noting USPS pickups are free, and flagging per-row cancellability. It stops short of saying how far back 'past' pickups extend, whether there is pagination or ordering, or auth/account scoping.

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

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

Front-loaded lead sentence names the resource and scope immediately, and the second sentence is a dense but justified field inventory given the absence of an output schema. It reads as a long run-on list and could be punctuated as bullets, but no sentence is filler.

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

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

With no output schema and no parameters, the description carries the return-value burden and does it well: carrier, time window, status, confirmation number, package count/weight, location, price and cancellability. Missing only history window, result ordering and any pagination/limit behavior.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline applies. The field list it does provide documents the response, not inputs, and is not wasted, but it cannot raise the parameter dimension further.

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 (scheduled and past USPS and UPS pickups on the account) with concrete attributes (confirmation numbers, day/time window, status). The reference to cancel_pickup signals it is the read/list counterpart to a mutation, so an agent can distinguish it from the other pickup-related sibling, get_pickup_quote.

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

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

Usage is implied rather than stated: 'Every carrier pickup on the account' plus 'whether it can still be cancelled with cancel_pickup' tells the agent this is the discovery step before cancelling. But there is no explicit when-to-use or when-not, and the sibling get_pickup_quote (for pricing a new pickup) is never mentioned, leaving that boundary 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?

The annotations already establish that this is a safe, idempotent read operation. The description adds useful behavioral context by stating that results are newest first, that payments may come from card, PayPal, or bank, and that each row includes status, description, and total in US dollars. It does not discuss pagination limits or rate limits, but with annotations covering the safety profile this is a solid addition.

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 short and front-loaded: the purpose and sibling distinction come first, followed by the table context and the downstream get_receipt use. Every sentence provides useful information without redundancy.

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

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

For a filterable list tool with no required parameters and no output schema, the description supplies enough context to understand what records are returned and how this differs from get_receipt. It leaves pagination and most filter semantics to the input schema, but the overall definition remains usable.

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

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

The description only indirectly covers one parameter by saying results are 'newest first,' which aligns with the sort default. It does not explain limit, offset, or the filtering behavior for search, status, from_date, or to_date, and with only 57% schema description coverage it does not compensate for the parameters whose schemas lack descriptions.

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

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

The description clearly identifies the resource as payments made to Pirate Ship and states the default ordering. It also explicitly distinguishes the single-record sibling tool by saying 'get_receipt shows one,' so an agent can tell list_receipts apart from get_receipt without opening either 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 clear context for using this tool: it lists account payments, while get_receipt shows a single receipt. It routes the agent to get_receipt when a receipt_id is available, but it does not explicitly exclude related listing tools such as list_transactions or list_refunds.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful context about what the table contains, including automatic refunds and the fields returned. It does not discuss pagination behavior or any rate-limit considerations, but the annotation coverage lowers that burden.

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 reasonably short and front-loads the resource and ordering behavior. The second sentence is dense but useful; there is minor redundancy between the first and second sentences.

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 does a fair job naming the returned refund fields and date-filtering behavior. However, for a 7-parameter list tool it leaves pagination, search, status filtering, and sort semantics under-explained.

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

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

Schema description coverage is 57%, so the description should compensate for undocumented parameters. It explains only that from_date and to_date narrow by request day and implies newest-first ordering, but does not add meaning for limit, offset, search, status, or the oldest sort option.

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 title and description make clear this returns label refund data, including status, amount, timing, tracking number, and recipient. The resource is specific, but the description does not explicitly distinguish it from nearby list/export/report siblings such as list_transactions or export_report.

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 frames the tool as the Reports > Refunds table but gives no explicit when-to-use guidance, prerequisites, exclusions, or alternatives. An agent can infer it is for viewing refunds, but must guess when to choose it over export_report or other list 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful domain behavior: unused labels cost nothing, so the result set includes zero-cost rows, plus what each row carries (status, return address, USD charge). It says nothing about ordering defaults, page size limits, or result size, which matters for a list endpoint.

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?

Short and front-loaded: the first sentence states the resource and the key fact (whether the customer used the label), the second enumerates the columns. Minor redundancy between 'Return Labels table' and 'every return label made with a shipment', but no wasted sentences.

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 seven optional parameters and no output schema, the description usefully enumerates what comes back (status, return address, USD charge), which is a real contribution. It is still incomplete on filter semantics, pagination defaults and ordering, leaving the agent to read the schema for anything beyond row content.

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

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

Schema description coverage is only 57% — search, status and the two date fields are documented, but sort, limit and offset have no schema description. The description compensates for none of this: it never mentions filtering by status, date-range scoping, pagination, or sort order, despite 'newest' being the default sort.

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 — pay-on-use return labels, their usage status, return address and USD charge — and frames it as the 'Reports, Return Labels table'. That is enough to distinguish it from shipment, refund and receipt listings. It never states a verb ('list') and doesn't name a sibling it displaces, so it stops short of 5.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative (e.g., export_report) guidance. Usage is only inferable from the 'Reports, Return Labels table' framing. An agent must guess whether to call this or export the same report when it wants bulk data.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real semantic content: weight is 0 'when each label sets its own,' and `default` marks the one preselected on new shipments. Those two disclosures are non-obvious and prevent misreading the data. It does not mention ordering, pagination, or whether the list is account-scoped.

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 blocks, front-loaded with the resource and scope, then the per-record field list, then the follow-up hint. Nothing is filler, though the second sentence is a dense run-on enumeration of fields that could be more scannable.

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

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

With no output schema and no parameters, the description correctly assumes responsibility for describing return values and does so field by field, including the edge case for weight and the meaning of `default`. What is missing is scale/ordering information for a list endpoint and any tie-break against `list_package_types`.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description instead spends its space explaining the shape of each returned record, which is the only parameter-adjacent semantics available 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?

The resource is named precisely ('Your Saved Packages from Settings') and the description enumerates exactly what each record holds: packaging type, size in inches, weight in ounces, signature, insured value, return label setting, flags, and the `default` marker. The read verb is only implied rather than stated, and the boundary with the sibling `list_package_types` is never drawn, 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?

It gives a concrete downstream usage rule: 'Use an id in update_saved_package or delete_saved_package,' which tells the agent where the returned ids belong. However it offers no when-not guidance and never distinguishes this from `list_package_types`, `create_saved_package`, or `get_label_settings`, which an agent could plausibly confuse it with. Usage is implied rather than scoped.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: it explains what a SCAN Form is (carrier scans all packages at once) and enumerates what is returned per address — labels_available, ship date, label count, PDF link. It omits pagination/result-size behavior, which matters given openWorldHint.

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

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

Front-loaded with the core purpose, then supporting detail, then the sibling pointer. Every sentence carries information, though the 'A SCAN Form lets the carrier scan all packages at once' explainer is domain background rather than invocation guidance and slightly dilutes the front-loading.

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

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

With no parameters and no output schema, the description must convey the return shape, and it does: per-address counts plus a list of forms with ship date, label count and PDF link. The main remaining gap is volume/pagination behavior for an open-world read, which an agent cannot infer.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no filtering input is required — it returns a breakdown across all Ship From Addresses.

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 ... USPS SCAN Forms') and scopes it clearly: forms are grouped per Ship From Address, each with PDF links, plus a count of labels that still lack a form. This is distinguishable from the sibling create_scan_form and from list_ship_from_addresses/list_return_labels at a glance.

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

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

Explicitly routes the agent to the alternative: 'Make one with create_scan_form.' That names the sibling and the condition that selects it. It stops short of stating when-not-to-use (e.g., no labels available, or when you only need shipments), so it is clear but not fully exclusive.

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 read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context beyond that by explaining the returned address semantics: ship-from location, return address, origin_is_return when they match, and the default marker. It does not cover pagination or ordering, but with annotations carrying the safety profile this is a solid disclosure.

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

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

The description is reasonably compact and front-loads the resource plus default-address information. The opening sentence is somewhat redundant with the following explanation, but the content is dense and useful rather than bloated.

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 a good job explaining the important returned fields and default semantics. It is nearly complete for a zero-parameter list tool, though it could mention whether all addresses are returned or whether pagination/order applies.

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

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

The tool has zero parameters, so there are no parameter semantics to document and the baseline is 4. The description correctly does not invent parameter details.

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

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

The description clearly identifies the resource as saved Ship From Addresses and explains that it includes return-address information and marks the default. It also distinguishes this read/list operation from related mutation tools by telling the agent to use an id in update_ship_from_address, delete_ship_from_address, or set_default_ship_from_address.

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 usage context by explaining that returned ids feed into update, delete, and set-default operations. It does not explicitly state when not to use this tool or contrast it with a competing list alternative, but no obvious list alternative exists for this resource.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the bar is lower, and the description still adds real behavior: results are ordered newest-first, every label the account bought is included unless filtered, and total/limit/offset define the paging envelope. It doesn't mention limits on result volume or rate constraints, keeping it from 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?

Content is front-loaded with the resource and default ordering before the table/filter detail. The second block is dense and clause-heavy, but nearly every clause carries information an agent needs to build correct filters.

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 tool with no output schema, the description compensates by enumerating the returned fields and explaining the paging envelope (total/limit/offset). Only minor gaps remain, such as the semantics of the sort enum values, which the schema's defaults largely cover.

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

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

With 70% schema coverage the description goes well beyond the schema: it specifies what search actually matches (name, email, tracking number, order id), that dates filter on the label creation day in the caller's timezone with an inclusive end day, that status/tracking_status/carrier/batch accept the display values shown in the table, and how total/limit/offset interact.

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 opening sentence names the resource (labels bought in Pirate Ship) and the exact fields returned — recipient, tracking, cost, status — plus the default ordering, 'newest first'. A second sentence anchors it to the Reports > Shipments table, which tells an agent precisely what dataset this represents, distinguishing it from siblings like export_shipments or get_shipment.

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 through the table analogy ('works like the table's search box') and the parameter walkthrough, but there is no explicit when-to-use/when-not guidance and no named alternative — an agent is left to infer that export_shipments covers CSV export and get_shipment covers a single 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 readOnly/idempotent/non-destructive, so the description's added value is the domain semantics: 'valid false means reconnect it in Pirate Ship' and the presence of an auto-sync flag. That tells the agent how to interpret the payload rather than just that the call is safe — a genuine addition beyond structured fields.

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

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

Front-loaded summary sentence followed by the field-level detail, with no filler or restatement of the title. The platform enumeration ('Shopify, Etsy, eBay, WooCommerce, Squarespace and others') is mildly expendable but serves to set the open-world expectation.

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 usefully covers the returned fields and the one non-obvious value ('valid false'). Pagination, ordering, and behaviour with zero connected stores are unaddressed, but for a simple no-arg list this is close to sufficient.

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

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

Zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description spends its words on the result shape instead, which is the right allocation for a no-argument tool.

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

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

States a specific verb and resource ('Stores and marketplaces connected to Pirate Ship for order import') and immediately characterizes the returned entity set (name, platform, active/authorised, auto-sync). An agent can distinguish this read-only enumeration from mutation siblings like sync_store_orders or create_batch without opening a schema.

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

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

Explicitly bounds scope with 'Connecting a store happens in Pirate Ship, not here', which pre-empts an agent trying to add a connection through this tool. It does not name the natural follow-up sibling (sync_store_orders) for triggering an import, so the when-to-use guidance is clear but not fully routed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, and the description adds real context beyond them: default ordering ('newest first'), USD amounts with sign semantics ('negative takes from the balance'), and the post-transaction balance. It omits pagination behavior (limit/offset interaction), which is the main remaining gap.

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

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

Two sentences, front-loaded with the resource and scope, then the field-level detail. The second sentence is dense but every clause (amount sign, balance-after, filter mapping) carries information; a small amount of trimming is possible but 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?

No output schema exists, and the description compensates by describing the returned record shape and the meaning of its numeric fields. For a read-only, zero-required-parameter list tool, that plus the schema on filters is sufficient for correct invocation.

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

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

With 57% schema coverage, the description usefully explains what the documented params mean in domain terms — 'narrow by day' for the date pair, 'the table's transaction types' for type, and 'works like its search box' for search. sort, limit and offset get no prose, but their enums, defaults and bounds are self-explanatory in the schema.

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

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

States a specific verb and resource ('Every charge, payment and refund on the Pirate Ship balance') and anchors it to a known surface ('The Reports, Transaction History table'). The enumerated record kinds (label purchase, payment, refund, carrier adjustment) distinguish it from narrower siblings like list_refunds or list_receipts without needing 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?

Usage is implied by the content description — an agent can infer this is the general ledger view rather than the typed lists (list_refunds, list_carrier_adjustments) — but no sibling is named and no when-not condition is given. Adequate but leaves the routing decision to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real value by disclosing that no validation occurs here and where validation actually happens. It stops short of saying what happens on an unparseable or partially parsed input.

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 transformation is stated first, then the context and the parse-only caveat. Nothing is repeated between sentences.

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 compensates by enumerating the returned fields, which is exactly what an agent needs. The only gap is failure behavior on malformed input, which is not addressed.

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

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

With one parameter at 100% schema coverage, the schema already documents the newline/comma-delimited free text and the 5–500 character bounds. The description adds only the informal framing ('a line copied from an email or an order'), which is marginal 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 ('Splits') plus the exact output fields (name, street, city, state, ZIP, country), so the transformation is unambiguous. The second paragraph ties it to create_shipment and clarifies it is parse-only, which separates it from the shipment/address-creation siblings.

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

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

Gives a concrete trigger ('free text such as a line copied from an email or an order') and a boundary ('It only parses; the address is checked when the shipment is created'). It implicitly routes the agent to create_shipment for validation, though it never names an explicit when-not-to-use case or a sibling that also parses text.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds useful context that the title appears on the Ship page and in reports, but omits auth requirements, reversibility, and failure behavior.

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

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

The description is two sentences, front-loaded with the action, and the second sentence adds useful display context without waste.

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

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

For a simple two-parameter mutation with rich annotations and no output schema, the description states purpose and visible effect. However, it remains incomplete about how to use `batch_id` and what happens on invalid input, so an agent must rely on the schema and sibling tools.

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

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

Schema description coverage is 0% for both required parameters. The description gives display meaning for `title`, but says nothing about `batch_id` such as where to obtain it or its expected format, leaving a material gap.

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

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

The description names a specific verb ('Changes') and resource ('a batch's title'), and scopes the effect to the title shown on the Ship page and in reports. This clearly separates it from sibling tools such as create_batch, delete_batch, get_batch, and list_batches.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. It does not explain when renaming is appropriate versus using related tools like update_label_settings, nor does it indicate what batch_id must reference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful scope details: it searches people this account shipped to before and matches by prefix rather than arbitrary substring. It still does not specify result limits or the shape of returned addresses.

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 short and front-loads the core purpose. There is slight redundancy between 'matching a name, email or phone' and 'matched by the start of their name (or email or phone)', but the UI context and usage hint earn their 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 simple two-parameter lookup tool with no output schema, the description provides enough context to call it correctly: historical recipient scope, prefix matching, and intended downstream use. Return cardinality and exact address fields remain unspecified but are minor gaps.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does explain that matching applies to name, email, or phone and is prefix-based, but it does not clearly document the `field` selector's default or the `query` length constraints.

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

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

The description states a specific resource and matching behavior: past recipients' addresses matched by name, email, or phone. It also distinguishes the tool from broader address tools by tying it to the Ship To autocomplete and to create_shipment's `to` field.

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

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

It gives a clear positive use case: select one of these suggestions as create_shipment's `to`. However, it does not explicitly say when not to use it or name alternatives such as list_ship_from_addresses or parse_address.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by naming what the setting affects downstream, but omits the key behavioral question for a 'set default' operation: what happens to the previously default address.

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 consequence. The second sentence partly restates the first, but the added 'get_rates and pickups' detail 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 one-parameter mutation with annotations and no output schema, this is nearly sufficient: purpose, scope and downstream effects are covered. The gap is the unstated effect on the existing default address and whether any confirmation is returned.

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

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

Schema coverage is 100% and the single parameter is documented with a clear provenance pointer ('id from list_ship_from_addresses'). The description adds nothing about the parameter, 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: makes one Ship From Address the default, which is clearly distinct from create/update/delete_ship_from_address siblings in the list. It does not explicitly name those siblings or state the single-default constraint, but the purpose is unambiguous.

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

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

The second sentence describes downstream impact (new shipments, get_rates, pickups), which implies why an agent would call this, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. update_ship_from_address vs. this) for comparison.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds real behavior beyond them: it starts Refresh Data for all stores, blocks up to wait_seconds, and can continue in the background. The 'running true' reference is unexplained (there is no `running` input and no output schema), which slightly muddies the disclosure but does not contradict any annotation.

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

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

Three short sentences, front-loaded with the action and scope, then sequencing and the edge case. 'Then list_import_orders shows the orders' is slightly awkward but still earns its place as guidance.

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

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

For a zero-required-parameter action tool with no output schema, it explains what happens, how long it blocks, that it can continue in the background, and the empty-store outcome. Remaining gaps (what the response actually contains, whether previously imported orders are re-pulled) are minor given annotation coverage.

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

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

Schema description coverage is 100% and the single parameter already documents range, default, and the '0 only starts it' behavior. The description restates the wait semantics ('waits up to wait_seconds') without adding format or interaction detail, 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 ('Pulls new orders') plus the scope ('from every connected store into ... Import list'), which is precise enough to distinguish it from list_import_orders and list_store_connections in the sibling 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?

Gives clear operational context: it triggers a refresh and the follow-up read is list_import_orders, plus the no-store case ('nothing is imported'). It stops short of explicit when-not-to-use or alternative routing (e.g. versus list_import_orders alone), so it is a strong 4 rather than a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds nothing about what is mutated or the consequence — e.g. whether orders re-enter store sync, trigger re-import, or whether the prior ignore state can be recovered. For a destructive-labelled mutation this leaves the agent without the context it needs.

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 tight sentence with the effect front-loaded and zero padding. It's efficient, though the brevity comes at the cost of the behavioral detail captured elsewhere.

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