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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the mutation profile is partly covered. The description adds that the link is established via a partner public key and accepts some configuration, but it never says what happens on a repeat call (non-idempotent), what is required on the partner side, or whether an existing link errors.

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 sentence is front-loaded and complete. The "Args:" block largely restates the schema description and could be dropped, but it is short and does not bury the purpose.

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 an output schema present, return values need not be explained, and the mutation annotations cover safety hints. Still, for an open-world, non-idempotent mutation, the description omits the prerequisite key-exchange step and duplicate-link behaviour, which an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single param is documented as "Link request (publicKey of partner organisation)", so the schema already carries the load and baseline 3 applies. The description's mention of "optional configuration" hints at fields beyond the loosely typed additionalProperties object, which is a small value-add but leaves the shape undefined.

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?

"Links another organisation into yours using their public key" gives a specific verb (link) and resource (organisation) plus the mechanism (public key). It is clearly distinguishable from read siblings like machship_get_organisation_links, but it does not name its obvious inverse, machship_remove_organisation_link, which would have sharpened the routing.

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

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

There is no when-to-use / when-not-to-use guidance and no stated prerequisites, such as needing the partner to supply their public key first (likely via machship_get_organisation_public_key) or needing link permissions. The agent must infer everything about the situation that calls for this tool versus the get/link-listing siblings.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the word "permanent," which hints at persisted recurring schedules, but it does not warn that repeated invocation on a non-idempotent endpoint may create duplicate pickup schedules, nor does it mention required auth or scope.

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

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

Two short, front-loaded statements with no filler; the purpose sentence comes first and the argument note follows. The 'Args:' block partially restates the schema but is justified given the payload has no declared properties.

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

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

This is a non-idempotent write taking an unconstrained nested object, and the description does not describe the pickup schedule structure, what a partial or invalid payload does, or how duplicates are avoided. Presence of an output schema excuses omitting return values, but the input-side and duplicate-risk gaps remain substantial for a mutation 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 payload schema is a bare object with additionalProperties {} and no defined properties, so the description's mention of companyLocationId and "pickup schedule details" is the only structural hint available and does genuinely add meaning. However, it stays vague about the schedule's actual shape (frequency, times, days), so it only marginally compensates for the vacuous 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: "Adds permanent scheduled pickups to a company location." The write-oriented naming plus the existence of the read-side sibling machship_get_permanent_pickups makes the distinction inferable, though the description never names that 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?

There is no when-to-use guidance, no prerequisites (e.g. the company location must already exist), and no routing to the alternatives such as machship_get_permanent_pickups to inspect existing schedules or machship_rebook_manifest_pickup. The agent is left to infer when this tool applies.

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

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

The annotations already disclose that this is not read-only, is open-world, non-idempotent, and non-destructive. The description adds useful context that reconciliation depends on configured carrier thresholds and that the operation is an 'attempt,' but it does not explain what is changed, what failure modes exist, or what permissions are required.

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 operation before listing the single argument. The Args section is slightly mechanical but still compact and free of unrelated detail.

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

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

The tool is a non-idempotent mutation with a nested request body and open-world behavior, so it benefits from annotations and the output schema. However, the description remains sparse on prerequisites, request payload structure, and operational side effects beyond mentioning configured thresholds.

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 high, but the body schema is a loosely typed object with no defined properties. The description adds a small amount of useful payload guidance by mentioning carrierInvoiceId and 'etc.', but it does not document the full reconciliation request shape.

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

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

The description states a specific verb and resource: attempting automatic reconciliation of carrier invoices based on configured carrier thresholds. It is clear enough for an agent to understand the operation, though it does not explicitly distinguish itself from related invoice-retrieval siblings such as machship_get_carrier_invoices.

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 'based on configured carrier thresholds' implies that the tool should be used when carrier thresholds are configured, but it does not give explicit when-to-use or when-not-to-use guidance. No alternative reconciliation or manual invoice workflow is named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety and idempotency profile is covered. The description adds nothing further — no note on duplicate-location behavior, required permissions, validation failures, or what the response contains — so beyond the annotations it contributes almost no behavioral context.

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 parts: a front-loaded purpose sentence followed by a compact Args block; there is no filler. The only minor inefficiency is that the Args block duplicates the schema almost verbatim rather than adding 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?

The tool takes a nested free-form object (additionalProperties: {}) plus a required companyId, so an agent needs to know which sub-fields are mandatory and which formats are accepted; the description gives none of that. It is helped by having an output schema and full annotation coverage, but the unstructured nested payload remains 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 100% and the single parameter's schema description already lists companyId, name, address, suburb, postcode, state, country, contactName, phone. The description's Args block largely restates that same field list, adding the 'etc.' hint that other fields exist but no format, required-vs-optional, or nesting guidance — baseline 3 is the right ceiling.

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 clear verb and resource ('Creates a new company location') and adds concrete examples of what a location is (warehouse, store, depot pickup point), which helps an agent disambiguate from 'search_locations' or location lookups. It does not explicitly contrast with the sibling mutations 'edit_company_location' or 'get_company_location', so it stops short of full sibling differentiation.

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

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

There is no when-to-use or when-not-to-use guidance: nothing says this is for net-new locations only versus using 'machship_edit_company_location' for existing ones, and no prerequisites (such as requiring a valid companyId) are mentioned. The create-vs-edit distinction is only implied by the tool name.

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

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

Annotations already declare readOnly=false, destructive=false, non-idempotent and openWorld=true, so the safety profile is covered structurally. The description adds the meaningful state detail that the resulting consignment is 'unmanifested', but omits what happens on success (does it book with the carrier?), whether duplicates are created on retry (relevant given idempotentHint=false), and any required permissions or validation failures.

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

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

Front-loaded with the action and purpose, then a compact structured Args breakdown. No redundant sentences; the 'core operation for booking freight' line earns its place as orientation. The trailing 'etc.' is the only weak spot.

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?

An output schema exists, so return values need not be explained. However, for a high-stakes nested-payload creation tool with no field-level schema enforcement, the description gives an incomplete field inventory and says nothing about required nested fields, validation behavior, or what 'unmanifested' implies for follow-up steps (manifesting).

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 nominally 100%, but the schema only describes a single untyped object with additionalProperties, so it conveys almost no field-level meaning. The description compensates by enumerating key fields (companyId, fromCompanyLocationId, toAddress with suburb/postcode/state/country, items with weight and dimensions, carrierId, serviceId, reference1/reference2), which is genuinely useful, but it ends with 'etc.' and never marks which nested fields are required. Baseline 3 reflects that this partially, not fully, documents a free-form nested payload.

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 ('Creates a new unmanifested consignment in Machship') plus the business purpose ('core operation for booking freight'). The 'unmanifested' qualifier and the mention of inline 'items (array of packages)' implicitly separate it from create_consignment_existing_items and create_consignment_with_complex_items, but those siblings are never named, so differentiation requires inference.

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

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

No explicit when-to-use or when-not-to-use guidance is given, despite three closely related create variants in the sibling list. 'This is the core operation for booking freight' provides context for the tool's role but does not tell an agent when to pick this over the complex-items or existing-items variants.

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, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds essentially no behaviour beyond that: nothing about what happens when a referenced item ID/SKU is not found, whether the consignment is created atomically, or that a write to a live carrier environment occurs (openWorldHint=true).

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

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

The purpose is front-loaded in one sentence with no filler. The trailing 'Args:' block largely restates what the schema already declares about 'consignment', making it mild redundancy rather than an asset.

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?

An output schema exists, so return values need not be explained. However, this is a write operation whose entire payload is an undocumented free-form nested object; the description gives no guidance on payload structure and does not point the agent at a schema-discovery tool such as machship_get_custom_schema or the sibling create tools for the expected consignment shape.

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 nominally 100% for the single 'consignment' parameter, so the baseline of 3 applies. In practice the schema is an empty additionalProperties object, so the description's note that it references existing saved item IDs is the only real meaning conveyed; it adds nothing about which fields are required or how item references should be shaped.

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 ('Creates a consignment') plus the defining constraint 'using previously saved company items (by item ID / SKU)', which lets an agent distinguish it from machship_create_consignment and machship_create_consignment_with_complex_items. It stops short of naming those siblings explicitly, so the 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?

Usage is implied: use this when the items already exist as saved company items and you can reference them by ID or SKU. There is no explicit when-not guidance, no mention of the alternative creation tools, and no stated precondition (e.g. that item IDs must already exist in the company) or failure behaviour for unknown IDs.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world, non-destructive write, so the safety profile is covered. The description adds only the distinctive payload trait (complexItems with packaging/DG data) and says nothing about creation side effects, whether a draft/pending consignment is produced, or carrier-dependent failures. No contradiction with annotations.

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

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

Front-loaded with the action and its differentiator in a single sentence, with no filler prose. The 'Args:' block is largely boilerplate that restates the only property, costing a little precision but not hurting readability.

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

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

This is a create operation taking one free-form nested object (schema is additionalProperties-only, so the '100% coverage' is misleading) with dangerous-goods payloads and an open-world annotation. The description gives no guidance on required consignment structure, valid complex item shapes, or where to discover the schema, which leaves an agent under-equipped for a genuinely complex tool. The presence of an output schema excuses it from explaining return values, but the input side remains thin.

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 nominally 100%, so the 3 baseline applies. The description does add one useful nugget the schema cannot express — that the consignment object must carry a complexItems array rather than standard items — but it does not describe the internal structure of those complex items or which other consignment fields are mandatory.

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 ('Creates a consignment') plus the distinguishing characteristic ('using complex item definitions ... instead of standard items'), which separates it conceptually from machship_create_consignment and machship_create_consignment_existing_items. It does not name those siblings, so the differentiation must be inferred from the parenthetical 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?

Implies the use case (when consignments need detailed packaging/dangerous goods data), which is a reasonable signal for choosing it over plain create_consignment. However, there is no explicit when-to-use/when-not and no named alternative, and no mention of prerequisites such as fetching a custom schema or consignment creation settings first.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive write. The description adds no behavioral detail beyond that: it does not say whether duplicate names are rejected, that repeated calls create duplicates (non-idempotent), whether permissions are required, or what happens on validation failure. For a mutation tool, this leaves an important gap.

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

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

The core sentence is front-loaded and earns its place. The Args block is redundant with the input schema and could be dropped, but it is short and does not obscure the purpose.

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?

An output schema exists, so return values need not be explained. However, the agent still lacks the valid entity types for "type" and confirmation of non-idempotent create semantics, which matter for a schema-mutating tool in an open-world API.

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

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

Schema description coverage is 100%, so the three parameters are already fully documented in the input schema, and the Args block merely restates those descriptions verbatim. It adds no meaning such as which values of "type" are valid or any structural constraints on the "schema" object beyond its being a JSON 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: "Creates a new custom schema to extend Machship entities with additional fields." This distinguishes it from sibling machship_get_custom_schema, machship_update_custom_schema and machship_delete_custom_schema by the verb alone. It is clear enough without opening the schema, though it does not call out the alternatives by name.

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

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

Usage is only implied by the "create" verb and the existence of get/update/delete siblings. Nothing tells the agent when to create a new schema versus updating an existing one, or what preconditions (e.g. an entity that supports extension) must hold.

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=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds two things beyond that: administrator-level authorization is required, and all items in the batch must share the same identityProvider/organisation. It does not explain batch failure semantics (all-or-nothing vs partial), duplicate-claim handling, or that passwords are submitted in plaintext.

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 prose lead is front-loaded and efficient, with the auth requirement and the shared-provider constraint in the right place. However, the bulk of the description is an Args enumeration that duplicates a 100%-covered schema field-for-field, so a meaningful fraction of the text does not earn 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?

An output schema exists, so return values need no explanation, and annotations cover the mutation safety profile. The description adds authorization and batching constraints, which is what an agent needs to invoke this correctly. The remaining gap is batch-level behavior on partial failure or duplicate identities, which matters for an array-input creation tool.

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

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

Schema description coverage is 100%, so every nested field (givenName, identifyingClaim, userAndCompanyLinks, etc.) is already documented with requiredness and types in the schema. The Args block largely restates that same field list, adding no format examples, link-object structure, or validation nuance. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ('Create identities in MachShip') plus a secondary effect ('assign companies and roles'), which separates it from machship_update_identity and machship_link_identities_to_companies. It also states a cross-item constraint (same identityProvider and organisation) that no sibling could satisfy. It does not explicitly name the sibling to use when the identity already exists.

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

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

It provides a prerequisite ('Requires administrator access') and a batching constraint ('All identities must belong to the same identityProvider and organisation'), which helps gate when the call is legal. It gives no guidance on when to prefer machship_update_identity or machship_link_identities_to_companies over creating new identities, so the alternative-selection path is left implicit.

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=false, destructiveHint=false, openWorldHint=true, and the description is consistent with a write operation. Beyond that it adds only that the item carries 'detailed packaging info' and is scoped to a company; it says nothing about duplicate-SKU conflicts, validation failures, or permissions, which is the most useful missing behavioral context for a non-idempotent create.

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 single-sentence purpose followed by a short Args list; nothing is padded. The Args block duplicates the schema descriptions, costing a small amount of space, but overall it is efficiently structured.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a create mutation over a loosely typed nested object, the definition omits SKU uniqueness behavior, minimum required item fields, and error expectations — meaningful gaps for correct invocation.

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

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

Schema description coverage is 100%, so the Args block largely restates the schema ('Company ID', 'sku, description, weight, length, width, height, etc.'). The nested item object is declared with additionalProperties: {} and no enumerated required fields, and the description does not fill that gap by naming which item fields are actually mandatory. Baseline 3 is appropriate.

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

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

States a specific verb and resource — 'Creates a new complex item (product/SKU with detailed packaging info) for a company' — and the word 'complex' plus the packaging-detail qualifier differentiates it from the simple-item retrieval siblings like machship_get_item_by_sku. It does not explicitly contrast with other creation tools such as machship_create_consignment_with_complex_items, but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites (e.g. that companyId must reference an existing company, whether SKU must be unique, or what happens on duplicate SKU), and no mention of any alternative tool. The agent must infer everything from the name.

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

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

Annotations already disclose readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the created record is in a draft/unrated/unassigned state and is later convertible to a full consignment, which tells the agent this is a non-terminal, non-destructive stage-setting write. It stops short of describing validation failures, required permissions, or what happens to the record if quoting fails.

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 definition is front-loaded in the first sentence and the second sentence adds lifecycle context rather than filler. The trailing 'Args' block marginally duplicates the schema's own property description, which keeps it from a 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 single-parameter create tool with an output schema and full annotation coverage, the description supplies enough: what is created, its lifecycle state, and how it is later used. Return values need not be explained because an output schema exists; only the nested object's required sub-fields remain opaque.

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 its fields (companyId, fromAddress, toAddress, items, reference1, reference2). The description's 'Args' block lists essentially the same field set ('companyId, from/to address, items, references, etc.'), adding almost no new 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 and resource ('Creates a pending consignment') and then defines what a pending consignment actually is: 'a draft/staging consignment that hasn't been rated or assigned to a carrier yet.' That definition distinguishes it from the sibling machship_create_consignment, though it never names that sibling directly, so the differentiation is inferential rather than explicit.

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

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

The line 'Pending consignments can be converted to full consignments after quoting' implies the workflow (stage now, quote, then finalize), which is useful implied usage guidance. However, there is no explicit when-to-use versus machship_create_consignment or machship_create_quote, and no prerequisites, exclusions, or error conditions 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 already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds that the call reaches out to carrier networks and is a non-destructive pre-step to a consignment, but it never says whether a quote record is persisted and later retrievable via machship_get_quote, nor anything about rate limits or cost of repeated calls — a meaningful gap for a create-verb tool flagged non-idempotent.

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 purpose, then Args, Returns and Examples in a predictable structure, with no filler sentences. The nested bullet list is a little dense in proportion to the single top-level parameter, but every line carries usable information.

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

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

For a nested-object tool with a 100%-covered but structurally empty schema, the description supplies the input field list, the returned rate fields, and a concrete usage example, which is close to what an agent needs. Remaining gaps are the sibling disambiguation and the persistence/retrieval behaviour of the created quote; return values themselves are already covered by the 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?

The input schema's quote object is effectively opaque (additionalProperties: {} with only a short parenthetical), so the description carries real weight: it enumerates companyId, fromAddress vs fromLocationId, toAddress components, items with weight in kg and dimensions in cm, and marks carrierId/serviceId as optional filters. Units and the address-or-location-ID choice are genuine value-adds; it still leaves item-level array shape and any per-item optional fields implicit.

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: it creates a freight quote and returns available carrier rates for a shipment, and it names the downstream step (consignment creation). The one ambiguity it leaves is against its nearest sibling, machship_create_quote_complex_items, which is never mentioned, so an agent still cannot tell from the description alone which quote tool fits which item shape.

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 an explicit when-to-use ('compare carrier prices and transit times before creating a consignment') and a when-not with a named alternative ('you already have a carrier in mind — use machship_create_consignment directly'). It stops short of covering the more likely confusion case, the complex-items quote sibling, so routing guidance is strong but incomplete.

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, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the mutation and external-carrier profile is known. The description's main addition is the return shape ("array of rate options with cost and transit info"), which is partly redundant given an output schema exists, and it says nothing about auth, rate limits, or whether quote calls are billable/committal. Adequate but not rich.

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 one-line purpose followed by compact Args/Returns/Examples blocks. Every line carries information an agent needs; no filler or restatement of the tool name.

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

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

Output schema and annotations cover return values and safety, and the description links behavior back to machship_create_quote. The one remaining gap is that the internal shape of complexItems is undefined in both schema and description, though the usage triggers and sibling references mitigate this.

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% but the schema itself is a bare object with additionalProperties, so the description genuinely adds meaning: the payload must carry a complexItems array 'instead of standard items', which is the key structural difference from machship_create_quote. It does not enumerate the complexItems fields, so 4 rather than 5.

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

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

States a specific verb and resource ("Creates a freight quote") and immediately narrows scope with "using complex item definitions (detailed packaging, dangerous goods, serialisation data)". This makes it distinguishable from the sibling machship_create_quote and from get_routes_complex_items 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?

Two explicit 'Use when' triggers are given: items with DG codes/serials/non-standard packaging, and specifically falling back here after machship_create_quote returns an item-structure validation error. That names both the condition and the alternative tool, leaving nothing 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is known. The description adds useful behavioral context by stating the key eligibility constraint: manifested consignments cannot be deleted. It omits partial-failure behavior or permission requirements, but the annotation coverage lowers the 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 definition is short and front-loads the core behavior and restriction before listing the parameter. The separate Args section largely duplicates the schema and has a minor type mismatch, but it does not obscure the main instruction.

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

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

For a one-parameter deletion tool with rich annotations and an output schema, the description supplies the essential eligibility rule and input meaning. It leaves some edge-case behavior unstated, but an agent has enough to invoke it correctly in the normal case.

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

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

The single parameter is fully described in the schema as 'Consignment IDs to delete', and the description repeats the same meaning without adding syntax or usage nuance. Schema description coverage is 100%, so a baseline score of 3 is appropriate; the description's 'number[]' phrasing also differs slightly from the schema's integer items.

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 multiple unmanifested consignments') and clearly scopes the operation to unmanifested consignments. The manifested restriction distinguishes it from broader delete operations and makes the tool's purpose 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?

Provides a clear usage condition by saying it deletes unmanifested consignments and cannot delete manifested ones, which tells the agent when the tool is applicable. It does not name alternative tools or explain how to handle mixed manifested/unmanifested ID sets, so it falls short of explicit alternatives 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description's one addition, 'This is irreversible,' reinforces the destructive hint rather than adding new information, and says nothing about permissions, error behavior for unknown IDs, or side effects.

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

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

Two short sentences plus an Args block, with the operation and its irreversibility front-loaded. The Args section is redundant with a fully described schema, which is the only wasted space.

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 destructive tool with rich annotations and an output schema, the definition covers what an agent needs in order to call it correctly. Minor gaps remain around error handling for invalid IDs and confirmation requirements, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single parameter's schema already documents 'DotNet class ID'. The Args block merely restates that, adding no format examples, sourcing guidance, or validation detail.

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

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

States a specific verb and resource ('Deletes a custom schema') plus the identifier used to target it, so the operation is unambiguous. It does not explicitly contrast with machship_get_custom_schema, machship_update_custom_schema, or machship_get_custom_schemas, though the delete 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?

The description gives no explicit when-to-use or when-not-to-use guidance, and no alternatives such as updating rather than removing a schema. Usage is only implied by the destructive nature of the operation.

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 readOnlyHint=false, so the safety profile is known. The description adds the useful nuance that the deletion is irreversible, confirming there is no reenable path, but it says nothing about cascade effects (e.g. linked companies, public keys) or required permissions for a batch destructive operation.

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

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

Two short sentences with the critical warning front-loaded; nothing is padded. The 'Args:' block duplicates schema information and is the only wasted element.

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?

An output schema exists and annotations carry the destructive/idempotency profile, so an agent has enough to call this correctly. For a batch irreversible delete, a sentence on what happens to dependent records would have made it 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 100% and the single 'ids' parameter is fully documented in the schema (array of positive integers, minItems 1). The description's Args block merely restates that without adding format, limits, or behavior for partial failures in a batch.

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

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

States a specific verb ('Delete') and resource ('identities with the given IDs'), which is clearly distinct from the sibling family (get_identities, disable_identities, update_identity). It does not explicitly name the closest alternative (disable_identities), so it falls just short of full sibling differentiation.

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

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

The 'irreversible' note implicitly signals this is the hard-delete path rather than the reversible machship_disable_identities, but there is no explicit when-to-use/when-not guidance, no prerequisite or permission statement, and no warning about what else is removed.

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 readOnlyHint=false, so the safety profile is structured data. The description adds the useful 'This action is irreversible' framing, but does not say what happens to consignments or records that reference the deleted item, nor what permission scope is needed. Adds some value beyond annotations, but leaves the main side-effect questions open.

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 the irreversible warning front-loaded, followed by a compact Args block. The Args line duplicates the schema and could be dropped, but nothing is verbose or buried.

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

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

An output schema exists so return values need no explanation, and the tool is a single-parameter mutation. However, for a destructive delete, the description does not state referential consequences or whether a soft/hard delete occurs, which is a meaningful gap for agent planning.

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 is documented as 'Company item ID to delete', so the description's Args block largely restates the schema. No extra meaning (format, where the ID comes from, cross-company scope) is added. Baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a saved item from a company'), which distinguishes it from the other delete siblings (delete_consignments, delete_custom_schema, delete_identities, delete_pending_consignments) by resource. It does not explicitly name those siblings, but the resource noun is unambiguous enough that an agent can route on it.

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

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

There is no guidance on when to use this versus alternatives or prerequisites — for example, whether to confirm the item exists via machship_get_item first, or whether the item must be unreferenced. The only guidance is the irreversibility warning, which is a consequence, not a selection criterion.

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, readOnlyHint=false and idempotentHint=false, so the safety profile is known. The description adds nothing beyond that: it does not say whether deletion is permanent or recoverable, whether a partially invalid ID list causes partial deletion, or whether related records are affected. With annotations covering the basics, this is a minimal pass but no added value.

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

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

The purpose statement is front-loaded in one short sentence with no filler. The trailing 'Args' block is redundant with the schema, which is the only wasted content.

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

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

This is a single-parameter bulk delete with full schema coverage, an output schema covering return values, and annotations covering the destructive/idempotent profile. The only residual gap is batch-failure semantics, which is minor for a tool this simple.

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 'ids' parameter is already documented in the schema with type, minItems and bounds. The description's 'Args' block simply repeats the schema text verbatim, adding no meaning such as a maximum batch size or behavior on unknown IDs. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Deletes ... pending consignments') and the plural scope ('one or more'). The word 'pending' implicitly distinguishes it from machship_delete_consignments, which handles non-pending consignments, but that contrast is never made explicit.

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

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

There is no guidance on when to choose this over machship_delete_consignments, no prerequisites (e.g. must the consignment still be unmanifested?), and no exclusions. The agent must infer that 'pending' is the discriminator from the tool name alone.

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

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

Annotations declare this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is largely covered. The description adds genuine context beyond that by naming the concrete consequence (identities can no longer log in). It does not say whether existing sessions are terminated, whether already-disabled IDs error, or what happens with unknown IDs.

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

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

The core sentence is front-loaded and wastes nothing. The trailing 'Args:' block duplicates the schema and is the only non-earning text, but it is brief.

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?

An output schema exists, so return values need no explanation, and the tool has only one required parameter. However, for a state-changing identity operation it omits error semantics and the relationship to reenable/delete, which an agent would need to invoke it confidently.

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

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

Schema description coverage is 100% and the single 'ids' array parameter is fully documented in the schema, including type, minItems, and positivity constraints. The description's Args block merely restates that, adding no new meaning such as batch-size limits or ordering behavior.

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

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

The description gives a specific verb and resource ('Disable the identities') plus the observable effect ('preventing them from logging in'). It stops short of differentiating from nearby siblings such as machship_delete_identities and machship_reenable_identities, so an agent must infer which of the three mutations to pick.

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

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

Usage is only implied: the 'preventing them from logging in' phrasing suggests a soft, reversible suspension rather than deletion, which hints at when to prefer this over machship_delete_identities. There is no explicit when-to-use, when-not-to-use, or prerequisite statement.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. Beyond that the description adds only 'any fields to update', which hints at partial-update semantics but never states whether omitted fields are preserved or cleared, nor what the response contains. For a mutation tool this is thin.

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?

Very short and front-loaded with the action, which is good, but the 'Args:' boilerplate restates the schema signature rather than adding information. The brevity here reads as under-specification rather than disciplined conciseness.

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

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

The tool takes a nested, unconstrained object, and the description never explains which location fields are editable or how to discover them (e.g. via machship_get_company_location). An output schema exists, so return values need not be described, but the input side is materially incomplete for a mutation of a complex nested payload.

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 nominally 100%, but the single parameter is a freeform object with additionalProperties {} and no documented properties, so the schema itself carries almost no field-level meaning. The description contributes the two key facts — an id is required and only changed fields need to be supplied — which is real added value, but it does not list valid fields or point to a source for them.

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

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

States a specific verb and resource: 'Edits an existing company location.' An agent can tell it mutates a location entity rather than creating or fetching one. However, it never distinguishes itself from siblings like machship_create_company_location or machship_get_company_location beyond the verb, leaving the sibling boundary implicit.

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

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

There is no when-to-use guidance, no mention of alternatives such as machship_create_company_location for new records, and no prerequisites or permissions noted. The agent must infer that this is the update path simply from the verb 'Edits'.

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. The description adds the useful manifested/unmanifested precondition, but says nothing about whether the update is full-replacement or partial, what happens to omitted fields, or permission requirements — relevant since destructiveHint=false could mislead an agent into assuming omitted data survives.

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 front-loaded sentences convey the operation and the key constraint with no padding. The trailing Args block merely restates the schema's own property description, which is minor waste but not harmful.

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

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

This is a mutation on an untyped nested object, and the description gives no guidance on how to construct the payload — no pointer to fetching the existing consignment for edit, no field list, no partial-vs-full semantics. Given the completely opaque nested schema, the description should carry far more weight than it does.

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 nominally 100%, but the single 'consignment' parameter is a free-form object with additionalProperties {} and no field structure, so the schema conveys almost nothing. The description only repeats 'updated consignment data including the consignment id' and adds no indication of expected fields, ID type, or nested shapes.

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 (edits) and a precisely scoped resource (an existing unmanifested consignment), and clarifies 'unmanifested' as 'not yet booked'. It does not name any of the many related siblings (update_reprice_consignment, update_consignment_statuses, get_unmanifested_consignment_for_edit), so differentiation still relies on inference from the name.

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

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

Provides a genuine exclusion — manifested consignments cannot be edited — which tells the agent when this call will fail. It stops short of routing the agent anywhere for the manifested case or suggesting the sibling used to fetch editable consignment data first (get_unmanifested_consignment_for_edit).

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 the useful definitional detail that "active" means in-transit, but says nothing about ordering, result limits, or whether child-company inclusion changes the result set. Since an output schema exists, the absence of return-value detail is acceptable, but the operational behavior (pagination semantics of startIndex starting at 1, max retrieveSize 200) is left entirely to the schema.

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 sentence is front-loaded and efficient. The appended Args list largely duplicates an input schema that already documents every parameter at full coverage, so it is mild overhead rather than value, but it is short and does not obscure the main statement.

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

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

For a read-only, single-entity-scoped list tool with rich annotations, a full input schema, and an output schema, the definition covers what matters: what is returned and for which company. The main residual gap is disambiguation from the crowded family of sibling consignment listers, which the description does not address.

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

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

Schema description coverage is 100%, so the baseline is 3. The Args block essentially restates the schema field descriptions ("Company ID", "Pagination start index", "Number to retrieve", "Filter by carrier") with no added meaning such as units, zero-vs-one-based indexing, or what happens when includeChildCompanies is omitted. It neither compensates for nor degrades 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?

"Returns all active (in-transit) consignments for a company" states a specific verb, resource, and a status qualifier that meaningfully narrows scope. The parenthetical "(in-transit)" lets an agent distinguish it from the many other consignment listers (all, recent, completed, unmanifested) without opening a schema, though it never names any of them explicitly.

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

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

There is no when-to-use or when-not-to-use guidance. The sibling list contains at least five near-identical retrieval tools (get_all_consignments, get_recent_consignments, get_completed_consignments, get_unmanifested_consignments, search_consignments), and the description gives no rule for choosing between them beyond the implied notion of "active". It also never mentions prerequisites such as needing a valid companyId or carrier scope.

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 covered. The description adds genuine behavioral detail beyond that: pagination, opt-in inclusion of deleted consignments and child companies, and local-time date filtering. It says nothing about result caps, throttling, or how filters combine, which keeps it at adequate rather than strong.

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 useful opening sentence is followed by a nine-line Args block that duplicates a fully documented schema, so a large share of the text does not earn its place. The single piece of genuine routing information is buried in the first line rather than front-loaded 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?

An output schema exists, so return values need not be explained. However, for a listing tool with nine parameters and aggressive sibling overlap, the description omits the allowed values for filterByEtaCompletedOrDespatch (no enums in the schema) and gives no basis for choosing this over machship_search_consignments or the specialized consignment getters.

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

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

Schema description coverage is 100%, so baseline is 3. The Args block largely restates the schema and is in places weaker than it (the schema gives defaults 1 and 40, a max of 200, and ISO 8601 format, none of which appear in the description). No added semantics for filterByEtaCompletedOrDespatch, which is a free-form string with no enum.

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: returns all consignments for a company, with date-range and status filtering. It is distinguishable from mutation siblings but not from the many read siblings (machship_search_consignments, machship_get_active_consignments, machship_get_recent_consignments, machship_get_consignments_by_carrier_id), since the description never explains what makes this the 'all' variant versus those.

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

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

There is no when-to-use guidance, no exclusions, and no named alternatives, despite the sibling list containing at least five closely competing consignment-listing tools. An agent must infer from the name alone that this is the broad/unscoped listing endpoint.

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 a small amount of real behavior – the response payload shape and the note that contentType is taken from the response header – but says nothing about error behavior for a missing ID or any download size constraints.

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

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

Two short sentences plus an Args block, front-loaded with the action. The Args section largely duplicates the schema, but it is brief and does not bloat the definition.

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

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

For a one-parameter read tool with an output schema and full annotation coverage, the description covers the essentials. It still omits what happens when the ID is invalid or the attachment is missing, which is the main open question an agent would have before calling a download endpoint.

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 there is a single required integer id already documented as 'Attachment ID'. The description's 'id (number): Attachment ID' restates the schema without adding format, source, or validity constraints, so this 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?

The description opens with a concrete verb+resource: 'Downloads the raw attachment file from Machship by attachment ID.' The 'by attachment ID' qualifier separates it from list-style siblings such as machship_get_attachments_by_consignment_ids and machship_get_consignment_attachments, though those siblings are never named.

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 by the phrase 'by attachment ID' – the agent must infer that an ID from a listing tool is a prerequisite. There is no explicit statement of when to prefer this over machship_get_attachments_by_consignment_ids or machship_get_attachment_pod_report, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned shape and the detail that contentType comes from the response header, but says nothing about size limits, base64 encoding overhead, or failure modes when a POD is unavailable for a consignment.

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

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

The purpose sentence is front-loaded and short, and the return shape is stated compactly. The trailing 'Args' block duplicates the schema field it already documents, which is mild redundancy but not bloat.

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

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

For a one-parameter, read-only download tool with a full output schema and complete annotations, the description covers what it does, what it takes, and what it returns. The only meaningful gap is guidance on missing/invalid POD documents.

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 a single required parameter at 100% schema coverage, the baseline is 3, and the description only restates 'id (number): Attachment ID' verbatim from the schema. It adds no meaning such as which attachment types qualify as POD reports or how to obtain a valid ID.

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

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

The description names a specific verb ('Downloads') and a specific artifact ('Proof of Delivery (POD) report'), plus the scope ('includes attachment and consignment details'). This clearly separates it from generic attachment readers like machship_get_attachment or machship_get_consignment_attachments, though it never names a sibling to sharpen the distinction.

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

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

Usage is only implied: an agent can infer you call this when you need a POD document for a known attachment ID. There is no explicit when-to-use, no exclusion, and no mention of what to do if the attachment is not a POD or no POD 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine value with the zip packaging and the note that contentType is taken from the response header, but it omits what happens when some consignments have no attachments or when an ID is invalid, and says nothing about payload size for a 40-consignment zip.

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 its constraint in one sentence, followed by the return shape, then the arguments. The 'Args' block is largely redundant with a fully documented schema, which is the only real 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 single-parameter bulk download the description covers scope, format and return keys, and an output schema exists so return values are already structural. Remaining gap is partial-failure/empty-attachment behavior, which is meaningful but not blocking.

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 'Args' block merely restates the schema ('ids (number[]): Array of consignment IDs (max 40)') including the same maxItems=40 constraint. No added meaning such as whether unknown/invalid IDs are ignored or cause failure, 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 and resource ('Downloads attachments for up to 40 consignments in bulk') plus the output form (zip), which implicitly separates it from the single-record attachment siblings. It never names those siblings (e.g. machship_get_attachment, machship_get_consignment_attachments), so the agent must infer the split from the 'bulk / max 40' phrasing.

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: 'in bulk' and the 40-item cap hint that this is the batched alternative to single-attachment fetching, but there is no explicit when-to-use or when-not-to-use statement and no alternative is named. An agent can guess correctly but is not guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds nothing beyond that — it does not say whether inactive or system roles are included, what permissions the caller needs, or whether the result depends on the calling identity's organisation. With annotations doing the heavy lifting, this is a minimal contribution.

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 sentence is front-loaded and efficient, but the trailing 'Args:' block duplicates the JSON schema verbatim and adds length without information. The definition is short overall, so it is not bloated, just partially 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?

An output schema exists, so return values need no explanation, and with one required scalar parameter this is a simple tool. Still, for a company-scoped lookup the description never clarifies authorisation or scope boundaries, leaving it merely adequate rather than 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 100% and the single parameter is already documented as 'Company ID' in the schema. The description's Args block restates exactly that, adding no format, source, or constraint details (e.g. whether companyId must be one the caller is linked to). Baseline 3 applies when the schema carries the parameter documentation.

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

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

The description states a specific verb and resource: 'Get all roles that are available to assign to users of a certain company.' This is recognizable as a read operation scoped to a company. No sibling tool deals with roles, so differentiation is implicit rather than explicit, which keeps it below a 5.

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

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

The phrase 'available to assign to users' implies the tool's place in a role-assignment workflow, but there is no explicit when-to-use statement, no mention of what to do when a role is missing from the result, and no named alternative. Usage is only derivable from purpose.

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 contributes nothing behavioral beyond that – no note on pagination, result volume, what status values exist, or what happens when the invoice has no entries – so it does not earn credit for added context.

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

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

The purpose sentence is front-loaded and the whole definition is short with no filler. The Args block largely duplicates the schema, which is mild waste, but the total length is appropriate for a two-parameter tool.

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

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

An output schema exists and annotations cover safety, so the description need not explain return values. However, for a subresource lookup the description gives no guidance on result size, pagination, or the valid status set, leaving a caller with an optional string filter unable to know what to pass.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured form and the baseline is 3. The description merely restates them ("carrierInvoiceId: The carrier invoice ID", "status: Filter entries by status") without adding accepted status values or default behavior, so it neither helps nor hurts.

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 ("Gets carrier invoice line entries") and scopes it to a single carrier invoice, which distinguishes it from the sibling machship_get_carrier_invoices that lists invoices themselves. It stops short of naming that sibling or otherwise differentiating the two explicitly, so the distinction must be inferred from the word "entries".

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

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

There is no statement of when to use this versus machship_get_carrier_invoices or any reconciliation sibling, nor any prerequisite or exclusion. The only usage signal is that status filtering is optional, which describes a parameter rather than a usage decision.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that with the max 100 records per call limit. It does not explain what happens when more than 100 invoices match (no pagination or truncation behavior) or whether any authentication/company scoping is required.

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

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

Front-loads the key fact (returns carrier invoice info, capped at 100 records) in the first sentence and presents filters in a clean list. The Args list is fully redundant with the input schema, so a little space is wasted, but the structure is easy to scan.

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?

An output schema exists, so return-value details need not be repeated, and annotations cover the safety profile. However, for a simple filtered list with no required parameters, the description omits two things an agent would want: how to handle results beyond the 100-record cap and how this differs from sibling invoice 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 100%, and the description's Args list restates each parameter exactly as the schema documents it, adding no new meaning. It does confirm all filters are optional, but repeats rather than enriches the schema. Baseline 3 is appropriate when the schema carries parameter documentation.

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: returns basic carrier invoice information, with a concrete cap of max 100 records per call. It does not differentiate itself from the closely related sibling machship_get_carrier_invoice_entries or from machship_get_posted_invoices, leaving an agent to infer which invoice-retrieval tool applies.

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

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

No when-to-use guidance or alternative is named. The use case (filtered invoice listing) is implied by the parameters, but the description never says when to choose this over machship_get_carrier_invoice_entries, machship_get_posted_invoices, or machship_get_invoice_by_document_number.

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 fully covered. The description adds that the payload is a base64 file plus a response-header-derived contentType, which hints at large binary returns, but it says nothing about size limits, failure modes, or what happens when no invoice exists, and the restated return shape is largely covered by the output schema.

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

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

The description is three short, front-loaded lines: purpose, return shape, then parameters. It is efficient overall, though the Args block duplicates the input schema verbatim and could be dropped without loss.

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 a single required parameter, full schema coverage, rich annotations, and an existing output schema, the description need only establish purpose and context, which it does. The remaining gap is error/edge-case behavior when a consignment has no commercial invoice, which is minor for a one-parameter read tool.

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

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

Schema description coverage is 100%, so the single consignmentId parameter is already documented in the schema, including its integer type and minimum bound. The description's Args block merely repeats "consignmentId (number): Consignment ID" without adding format, source, or lookup guidance, 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?

"Returns the commercial invoice PDF for a consignment" gives a specific verb (returns) and a precise artifact (commercial invoice PDF), which separates it from sibling PDF tools such as get_consignment_label_pdf, get_dangerous_goods_pdf, and get_special_instructions_pdf. The parenthetical "used for international shipments" narrows the domain further, but 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?

"Used for international shipments" implies when the tool applies, which is more than most PDF getters offer. However, it gives no guidance on prerequisites (e.g. the consignment must already exist or have a commercial invoice attached) and never names alternatives such as machship_upload_commercial_invoice or machship_get_consignment_pdf_file_info.

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, non-destructive, and open-world. The description adds useful auth-related failure behavior: 401 means check MACHSHIP_API_TOKEN, and 403 means the token lacks company-list permission. It also documents returned company fields, though the existence of an output schema makes that partly redundant.

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

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

The description is front-loaded with the core purpose and organized into Args, Returns, Examples, and Error Handling. It is somewhat longer than strictly necessary because the output schema already covers return fields, but the structure remains easy to scan.

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

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

For a two-parameter read-only listing tool, the description covers purpose, usage alternatives, parameter meaning, error handling, and example scenarios. With rich annotations, full schema coverage, and an output schema, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema already explains both parameters. The description repeats the hierarchy filter meaning for atOrBelowCompanyId and output format default for response_format without adding substantially new syntax or behavioral detail.

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

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

The description states a specific verb and resource: 'Returns all companies accessible to the authenticated user.' It also explicitly distinguishes this tool from machship_get_company_carriers, which handles carrier/service information rather than company listing.

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

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

It gives concrete use cases, including listing accessible companies and resolving a company name to an ID. It also provides an explicit exclusion: don't use this for carrier/service info, use machship_get_company_carriers instead.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is fully covered. The description adds the useful workflow dependency (must be called before consignment/quote creation), but says nothing about permissions, scoping to the caller's organisation, pagination, or behaviour when a company has no configured carriers. The return-shape block largely duplicates the existing output schema rather than adding behavioural context.

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 usage guidance before the detail, and the Examples block is genuinely useful. However, the inline JSON return-shape and the Args list duplicate structured data the agent already receives, adding length without new information.

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

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

For a two-parameter read tool with a full output schema and rich annotations, the description covers purpose, timing, alternative routing, and return structure. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The Args section merely restates 'companyId (number): Company ID' and the response_format default/enum verbatim, adding no meaning such as whether the ID is an internal Machship company ID versus an external reference. Baseline 3 applies.

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

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

States a specific verb and resource with explicit scope: 'Returns all available carriers, carrier accounts, and freight services for a company.' It also names the sibling it is not (machship_get_companies), so an agent can distinguish it 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?

Gives an explicit when-to-use rule ('Call this before creating consignments or quotes'), a concrete motivating example (need a serviceId for createConsignment), and an explicit when-not-to-use with the alternative tool named. Nothing 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, destructiveHint=false and openWorldHint, so safety behavior is covered structurally. The description adds only the clarification of what a company location represents; it says nothing about error behavior when the id does not exist or about permission requirements.

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

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

The purpose sentence is front-loaded and free of padding. The trailing Args block duplicates the schema's parameter description and could be dropped without loss.

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

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

For a one-parameter read tool with full annotation coverage and an output schema that describes the return shape, the description supplies what an agent needs to call it. The only meaningful omission is routing guidance versus the list sibling.

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 id parameter is fully documented in the schema, including type and bounds. The description's Args block merely restates that same information, adding no new meaning such as format, source, or how to obtain a valid id.

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

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

States a specific verb and resource ("Returns details for a single company location") and clarifies the domain with parenthetical examples (warehouse, store, depot). It does not distinguish itself from the sibling machship_get_company_locations list tool, so an agent must infer the single-vs-many split from the wording alone.

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

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

The word "single" implies this is the lookup-by-id path as opposed to a listing, which is weak but real usage guidance. There is no explicit statement of when to prefer this over machship_get_company_locations, nor any prerequisite or not-found 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the meaning of 'locations' via examples (warehouses, stores, depots) and does not discuss ordering, pagination, or access requirements. With annotations and an output schema present, this is adequate but not rich.

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 behavior. The Args section largely restates the schema, which is minor redundancy rather than a structural problem.

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 one-parameter read tool with annotations and an output schema, the definition gives enough information to invoke it correctly. The main missing context is explicit guidance on choosing between this tool and the related location-retrieval siblings.

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

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

Schema description coverage is 100%, and the single companyId parameter is fully documented in the schema. The description repeats 'Company ID' without adding format, validation, or lookup guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Returns all locations (warehouses, stores, depots) for a given company.' This clearly states the operation and scope. It does not explicitly contrast with close siblings such as machship_get_company_location or machship_search_locations, so it stops short of full sibling differentiation.

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

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

The phrase 'for a given company' implies company-scoped bulk retrieval, which is useful context. However, it gives no explicit guidance on when to use this instead of the singular machship_get_company_location or the location-search siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the structured data: a hard cap of max 2000 results. It says nothing about whether results are truncated versus erroring at the cap, ordering, or date-range edge semantics, so credit is limited.

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 sentence is front-loaded and efficient, correctly establishing purpose and result cap. However, the four-line Args block duplicates the input schema word-for-word and consumes roughly two-thirds of the text without adding information, which is filler rather than earned content.

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

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

With an output schema present and full annotation coverage, the description need not explain return values or safety. It states the resource, the date-range scoping, and the 2000-result ceiling, which is enough for correct invocation. The remaining minor gap is the absence of any disambiguation from the many other consignment-listing siblings.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The Args block simply restates each schema description verbatim (including 'ISO 8601'), adding no format examples, timezone handling, date inclusivity, or guidance on includeChildCompanies. Baseline 3 applies since the schema does the work and the description adds nothing.

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

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

The description names a specific verb and resource ('Returns completed (delivered) consignments') and adds scope ('within a date range'), which distinguishes it from status-based siblings like active or unmanifested consignment getters. It does not explicitly name which sibling to use instead when the agent wants all or recent consignments, so it falls short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance despite a crowded sibling set (get_all_consignments, get_recent_consignments, get_active_consignments, search_consignments, get_consignments_by_carrier_id). The only implicit signal is that 'completed (delivered)' implies a status filter, leaving the agent to infer selection among many near-duplicate retrieval tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful context that deleted consignments exist and are excluded unless includeDeleted is set, plus that request GUIDs are optional response fields. It says nothing about behavior when the ID is unknown or about the scope of 'full details'.

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

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

The purpose sentence is front-loaded and the whole definition is two short blocks with no filler. The 'Args' list duplicates the input schema, which is mild redundancy but does not bloat the text.

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

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

With a full output schema and rich annotations, the description need not explain return values, and the parameters are fully covered. However, for a single-record lookup among many consignment getters, it omits the routing information (which sibling to use for multiple IDs, references, or searches) that would make the definition self-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?

Schema description coverage is 100%, so the schema already documents all three parameters. The 'Args' block largely restates those schema descriptions verbatim ('Consignment ID', 'Include deleted consignments'), with only a small addition ('in response' for request GUIDs). This is baseline-3 territory: accurate but not additive.

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

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

The description states a specific verb and resource ('Returns full details for a single consignment by ID'), so an agent knows exactly what the tool fetches. It does not distinguish itself from close siblings such as machship_get_consignments_by_ids, machship_search_consignments, or machship_get_consignment_for_clone, which an agent could easily confuse it with.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'by ID' implicitly signals that a consignment ID is required, but nothing says when to pick this over the batch lookup, the search tool, or the clone-specific getter.

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 read-only, idempotent, non-destructive behavior, and the description adds a meaningful nuance beyond them: the response contains attachment metadata only, not file contents. It says nothing about permissions, rate limits, or what happens when a consignment has no attachments, but the core behavioral distinction is present.

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 two-line description is front-loaded and efficient, with the important metadata-not-contents caveat in the first sentence. The Args block merely restates the schema and is slightly redundant, but it costs little space.

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

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

For a single-parameter read tool with full annotations and an output schema, the description covers the essential scope and return-content distinction. Minor omissions such as behavior for consignments without attachments are acceptable given the structured metadata available.

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

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

There is only one parameter and the schema already documents it at 100% coverage with the same 'Consignment ID' wording, so the description adds no semantic detail. The baseline of 3 applies when the schema fully carries parameter 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 ('Returns') and resource ('attachment metadata') scoped to a single consignment, and clarifies it excludes file contents, which helps separate it from attachment-content tools. It does not explicitly name the closest siblings such as machship_get_attachments_by_consignment_ids or machship_get_attachment, so it falls short of full sibling differentiation.

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

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

The 'metadata (not file contents)' phrasing implies when this tool is appropriate versus retrieving actual files, but no sibling is named and no explicit when-not guidance is given. An agent must infer the choice against machship_get_attachment and machship_get_attachments_by_consignment_ids.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds real context beyond them: the pending ID must be in a transformed/linked state, and the result may be absent ('if it exists') — a precondition and outcome caveat an agent could not infer from annotations alone.

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

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

One front-loaded sentence captures purpose and precondition. The trailing Args block restates schema content and is mild redundancy, but nothing is padded 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?

For a single-param read tool with a full output schema and rich annotations, the description supplies the key missing piece — the precondition that the pending consignment must be linked — which is what an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented as 'Pending consignment ID' in the schema, so the description's Args block repeats it verbatim. No extra semantics (format, lookup scope) are added, which is the baseline when the schema does the work.

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

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

States a specific verb and resource (get consignment details) and adds a meaningful qualifier: the pending ID must already have been transformed/linked into a consignment. This separates it in spirit from machship_get_pending_consignment and machship_get_consignments_by_pending_ids, though it 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?

The phrase 'if it exists' implies this tool applies only after a pending consignment has been linked, and suggests a null/absent result otherwise. However, there is no explicit guidance on when to choose this over the sibling pending-consignment or batch-by-pending-ids tools, leaving the routing decision partly 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 and destructiveHint=false, so safety is covered. The description adds one useful behavioral detail beyond them: companyId defaults to the authenticated company. It does not say whether the defaults are carrier-dependent or how the settings change per company, which is the main behavioral question for this tool.

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

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

Two short, front-loaded sentences with no padding; the purpose precedes the argument note. The trailing "etc." is mildly vague about what else is returned, but the structure is efficient overall.

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?

An output schema exists, so return values need not be spelled out, and with a single optional parameter the description covers the invocation surface adequately. The only shortfall is the missing explicit link to the create-consignment tools, which matters given how many creation variants exist.

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

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

Schema coverage is 100% and the schema already labels companyId optional, but the description supplies meaning the schema lacks — that omitting it falls back to the authenticated company's context. That is a real invocation-relevant semantic addition, even if small.

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 ("Returns settings and defaults needed for creating consignments for a company") and enumerates what the payload contains (required fields, defaults). It is clearly distinguishable from the many machship_create_consignment* siblings because it is a read that feeds them, although it 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 only implied through the phrase "needed for creating consignments" — an agent can infer this is a pre-flight lookup, but the description does not say "call this before machship_create_consignment" or scope it to a specific creation flow. There are no exclusions or alternatives named.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and an output schema exists, so the safety profile and return shape are covered. The description usefully adds that the payload is clone-ready for the create endpoint, but it does not disclose what is stripped or must be changed (IDs, references, dates) before re-submission — a notable omission for a clone helper.

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

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

The purpose and the downstream endpoint are front-loaded in one sentence, followed by a compact args list. Nothing is wasted, though the 'Args' restatement of the schema field adds little.

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

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

For a one-parameter read tool with full annotation coverage and an output schema, the definition supplies what an agent needs to choose and invoke it. The only gap is practical guidance on mutating the returned payload before creating the copy.

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% for the single 'id' parameter, so the description merely restates 'Consignment ID to retrieve in clone format'. No additional semantics such as whether the ID is a consignment or pending consignment identifier are provided, 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 ('Get the details of an existing consignment') and adds a distinguishing purpose: the output is formatted for direct submission to createConsignmentWithComplexItems. That clearly separates it from plain read siblings like machship_get_consignment, though it does not name 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?

The intended workflow is unambiguous: call this when you want to copy a consignment, then feed the result to createConsignmentWithComplexItems. There is no explicit when-not guidance or named alternative for read-only inspection, which keeps it from 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, open-world behavior, so the safety profile is covered. The description adds one useful operational detail (contentType comes from the response header) but says nothing about failure modes such as labels not yet generated or consignment not manifested.

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 statement and short overall, but the explicit return-field listing and the Args block largely duplicate the output schema and input schema, adding length without new meaning.

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 one parameter, an output schema, and rich annotations, only modest description content is required, and the return shape plus header caveat are covered. It still omits availability timing and any routing guidance among the many label/PDF siblings, which is the main gap.

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

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

Schema coverage is 100% and the description's 'consignmentId (number): Consignment ID' merely restates the schema. It adds no format hints, no source of the ID, and no note that the schema types it as an integer rather than a number.

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: 'Returns the consignment label PDF', which an agent can immediately map to a label-retrieval action. It does not distinguish itself from close siblings such as machship_get_consignment_pdf_file_info or machship_get_item_label_pdf, so the caller must infer the difference.

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 or when-not-to-use guidance and never names an alternative such as the file-info or PDF-file-info variants. The agent is left to guess whether this fetches bytes, metadata, or both.

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 elsewhere. The description adds useful context about the nature of the returned content, but says nothing about volume, ordering, or what happens when a consignment has zero notes, and an output schema already covers the return shape.

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

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

The core sentence is front-loaded and wastes no words. The appended Args block is redundant with the schema but is short enough not to hurt readability.

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 one required parameter, full schema coverage, rich annotations, and an output schema, the description covers what an agent needs to invoke the tool correctly. The only meaningful omission is any routing guidance versus the many consignment-related siblings.

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

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

Schema description coverage is 100% and the single parameter already documents itself as "Consignment ID" with type and bounds. The description's Args block simply restates that, adding no new meaning such as where to obtain the ID or whether pending consignment IDs are accepted.

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

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

The description names a specific verb and resource ("Returns all notes attached to a consignment") and clarifies what counts as a note (internal comments, delivery instructions). It does not, however, differentiate itself from nearby siblings such as machship_get_consignment_attachments or machship_get_special_instructions_pdf, which an agent could easily confuse with this one.

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

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

Usage is only implied: an agent can infer it should call this when it needs commentary attached to a known consignment ID. There is no explicit statement of when to prefer this over machship_get_consignment or the attachment/instruction tools, and no prerequisites or exclusions are given.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description is not required to carry the safety profile. It does add the useful behavioral detail that the payload is base64-encoded rather than a binary stream, but it says nothing about size limits, rate limits, or what happens for a consignment without a label.

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 sentence is front-loaded and earns its place, but the trailing 'Args' block duplicates the input schema verbatim and adds no information. Removing it would lose nothing and would sharpen the definition.

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

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

For a single-parameter read tool with a full output schema and rich annotations, the description supplies the one thing the schema does not make obvious: that the file arrives as base64 inside object.content. What remains missing is disambiguation from the sibling PDF-retrieval 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 100% for the single parameter, so the schema already defines consignmentId as a positive integer. The 'Args' block merely restates 'consignmentId (number): Consignment ID' without adding format, sourcing, or example detail, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Returns the consignment label PDF') and qualifies the format ('as JSON'), which implicitly contrasts with the binary-label siblings like machship_get_consignment_label_pdf. It stops short of naming that alternative explicitly, so the differentiation is inferential rather than stated.

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

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

The 'as JSON / base64' framing implies when this tool is preferable to a raw-PDF sibling, but there is no explicit when-to-use or when-not-to-use guidance and no sibling is named. The agent must infer the selection rule from the output-format hint alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the batch cap of 10, which is already encoded in the schema via maxItems, so it contributes little new behavioral context beyond noting the batching constraint in prose.

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 purpose and the 10-item cap are front-loaded in the first two sentences. The trailing 'Args:' block largely duplicates the schema, which is mild redundancy but not harmful given the overall brevity.

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?

A single-parameter read tool with a full schema, rich annotations and an output schema needs little prose. The definition covers purpose, lookup key and the batch limit, leaving nothing an agent needs in order to call it correctly.

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

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

Schema description coverage is 100% and the single parameter is fully documented with type, minLength, minItems and maxItems. The description merely restates 'Array of carrier consignment IDs (max 10)', adding no format or syntax detail beyond the schema, which is the expected 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 ('Finds') and resource ('consignments') and pins the lookup key to the carrier's own consignment/tracking ID, which implicitly differentiates it from siblings like get_consignments_by_ids or get_consignments_by_reference1/2. It stops short of naming those alternatives, but the resource distinction is clear enough to select correctly.

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

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

The phrase 'carrier's own consignment/tracking ID' implies the lookup context (you have an external carrier ID, not a Machship ID), but there is no explicit when-to-use/when-not-to-use statement and no named alternative. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the batch size ceiling, which is also in the schema, and says nothing about partial results (what happens when some IDs don't exist) or request throttling.

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 statement is one front-loaded sentence with no wasted prose. The trailing 'Args:' block largely restates the schema entry for the single parameter, which is mild redundancy but not harmful.

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

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

For a single-parameter, read-only batch fetch with a full output schema and complete annotations, nothing essential is missing. The one behavioral fact an agent needs beyond structured fields — the per-request cap — is stated up front.

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

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

Schema description coverage is 100%, so both the type (integer array, positive, maxItems 100, minItems 1) and the meaning of 'ids' are already documented. The description repeats the same 'max 100' note without adding format, ordering, or ID-source guidance, 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?

The description uses a specific verb and resource ('Returns details for multiple consignments by their IDs') and signals batch scope, which separates it from single-record siblings like machship_get_consignment. It does not, however, explicitly distinguish itself from the other lookup siblings (by_reference1/2, by_carrier_id, search_consignments), so the agent must infer the boundary.

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

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

Usage is only implied: 'multiple ... by their IDs' hints at batch lookup when IDs are already known, and the max-100 constraint scopes it. There is no explicit when-to-use/when-not guidance or named alternative for reference-based, carrier-based, or free-text searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description's only added behavioral fact is the 100-consignment cap, which is already expressed by maxItems in the schema; it says nothing about partial results, missing/invalid IDs, or ordering. With annotations carrying the burden, this is adequate but thin.

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 prose is short and front-loaded, but the 100-item maximum is stated three times (twice in the description, once in the schema) and the 'Args:' block duplicates the schema verbatim. The repetition costs space without adding 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?

An output schema exists, so return values need not be explained, and the tool is a simple one-parameter batch read. However, the definition never clarifies what a 'pending' consignment ID is versus a regular consignment ID or what happens when IDs are not found, which is the main ambiguity an agent would face.

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 'Pending consignment IDs (max 100)' plus minItems/maxItems constraints. The description restates the same cap without adding format, ordering, or error semantics, 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 ('Get consignment details'), resource ('consignments'), and lookup key ('Pending Consignment IDs'), which meaningfully distinguishes it from machship_get_consignments_by_ids and the single-record machship_get_consignment_by_pending_id. It does not name those siblings explicitly, so differentiation is inferable rather than stated.

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

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

Usage is implied by the batch framing and the 100-item cap, but there is no explicit guidance on when to use this versus machship_get_consignment_by_pending_id for a single ID or machship_get_consignments_by_ids for already-created consignments. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered structurally. The description adds the meaningful operational constraint of max 10 references per request, but says nothing about matching behavior (exact vs partial match, case sensitivity) or what happens with unmatched references.

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 plus a compact args block; the batch cap is stated up front. The Args section duplicates the parameter already covered by the schema, making it slightly redundant but not harmful.

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 lookup with a full output schema and rich annotations, the core need is covered, but the description leaves the agent unable to decide between this tool and reference2 or IDs-based siblings. The max-10 cap is the main value added.

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 fully documented in the schema, including minLength and maxItems. The description's Args block largely restates the schema rather than adding semantics such as whether references must be exact or how duplicates are handled.

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 (finds) and resource (consignments) scoped to the Reference 1 field, with a clarifying example (order number). It doesn't distinguish itself from the near-identical sibling machship_get_consignments_by_reference2, which an agent would need to disambiguate.

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 explicit guidance on when to choose Reference 1 versus Reference 2, consignment IDs, or the search tool, despite a crowded sibling set of consignment lookups. The only usage constraint offered is the batch cap of 10.

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 behavior, so the safety profile is covered. The description adds only the 10-item cap, which is also in the schema, and says nothing about behavior like partial-match semantics or what happens when a reference matches multiple consignments.

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

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

Two short, front-loaded sentences followed by a brief args list; nothing is padded. The max-10 limit appears twice (body and args), which is minor redundancy rather than bloat.

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?

An output schema exists and the tool is a simple single-parameter lookup, so the description needn't explain return values. It is nearly complete; the only gap is match semantics on the reference values.

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 there is a single parameter, so the schema fully documents 'references' with the max-10 constraint. The description's args block merely restates that same information, adding no semantics such as whether values are case-sensitive or exact-match.

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 ('Finds consignments by their Reference 2 field') and names the exact lookup key, which distinguishes it from the sibling machship_get_consignments_by_reference1 without opening either schema. Scope limit (max 10) is included up front.

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 no when-to-use guidance or alternatives. It does not say to use search_consignments or get_all_consignments when the reference field is unknown, nor does it list any exclusion conditions. Usage is only implied by the field name.

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