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

Annotations indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it uses a public key, but does not disclose side effects, return behavior, or permission requirements. Adequate but not comprehensive.

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 very concise: two sentences and an args list. The main action is front-loaded, and every sentence adds value without repetition or fluff.

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, no output schema, and siblings for link management, the description covers the core action but lacks details on return values or expected outcomes. It is minimally viable but could provide more context.

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 describes the 'request' parameter as a link request with publicKey. The description adds 'optional configuration', which is not in the schema description, providing additional semantic value. Schema coverage is 100%.

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

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

The description clearly states the verb 'Links' and the resource 'another organisation into yours' using a specific method (public key). It distinguishes from related tools like remove_organisation_link and get_organisation_links.

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

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

The description implies usage when you have the partner's public key but does not explicitly state when to use this tool versus alternatives (e.g., remove or get links). No exclusions or prerequisites are provided.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no further behavioral context beyond confirming it's an additive mutation. No mention of side effects, auth requirements, or error conditions.

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 concise (two sentences) with no wasted words. However, it could be more informative by incorporating usage cues without increasing length significantly.

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 tool that creates permanent schedules with a nested object parameter, more detail is needed about schedule format, expected behaviors, and response. The description is too sparse given the complexity.

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 'payload' parameter. The tool description aligns but adds minor detail about 'pickup schedule details'. Baseline 3 is appropriate since the schema already covers the 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?

The description uses a specific verb ('Adds') and resource ('permanent scheduled pickups to a company location'), clearly distinguishing it from sibling tools like machship_get_permanent_pickups (retrieval) and machship_edit_company_location (editing).

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

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

No guidance on when to use this tool versus alternatives, prerequisites (e.g., existence of company location), or when not to use it. The description leaves the agent without context for invocation decisions.

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 indicate it's not read-only, not destructive, not idempotent, but the description does not elaborate on side effects, success/failure behavior, or retry safety. Minimal behavioral disclosure beyond the annotation flags.

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

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

One sentence and an args list; not verbose but could be more compact. The structure is functional but lacks front-loading of key 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?

No output schema and no description of return value. The complex nested parameter 'body' lacks detailed subfield documentation. Context about what the tool returns or when it's appropriate 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?

Single parameter 'body' with vague description in schema. The description adds 'carrierInvoiceId, etc.' hinting at required fields, but the schema allows any additional properties. Schema coverage is 100% but lacks structural 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?

Description states 'Attempts automatic reconciliation of carrier invoices' which is a clear verb+resource. However, it does not distinguish from sibling tools like get_carrier_invoices or get_carrier_invoice_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?

No guidance on when to use this tool vs alternatives, nor any prerequisites or conditions. The description lacks context about when auto reconciliation is applicable.

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 indicate a write operation, but description adds no extra behavioral context like validation, idempotency, or error conditions. Minimal value beyond annotations.

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

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

Two efficient sentences with a clear purpose and parameter list. No fluff, front-loaded correctly.

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?

Simple tool but lacks details on required subfields, expected response, and prerequisites. Not fully self-contained for an agent to use 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 description lists fields, but largely repeats schema info. Decent but does not add significant meaning beyond what's already provided.

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?

Description clearly states 'Creates a new company location' with specific subtypes and distinct verb, differentiating from sibling tools like edit and get.

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

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

No guidance on when to use this tool versus alternatives such as edit_company_location or other creation tools. Lacks when/when-not criteria.

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 indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds that the consignment is unmanifested, but does not disclose side effects, auth requirements, or other behavioral traits beyond what annotations imply.

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

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

Two sentences with a bullet list of args. Front-loaded with purpose. No redundant information, but could be more structured with required vs optional fields.

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

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

Lacks information on return values (no output schema) and error conditions. For a core booking operation, agents need to know what is returned upon success or failure. Does not mention idempotency or state changes beyond creation.

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?

While schema coverage is 100%, the description adds value by listing expected sub-fields (toAddress components, items structure, references) that are not in the schema description. This helps agents understand typical consignment structure, though optionality is not specified.

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

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

The description clearly states it creates a new unmanifested consignment and is the core operation for booking freight. It specifies the verb and resource, but does not explicitly differentiate from sibling creation tools like create_pending_consignment or create_consignment_existing_items.

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

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

No guidance on when to use this tool versus alternatives such as create_pending_consignment or create_consignment_with_complex_items. Lacks prerequisites, exclusions, or typical use cases.

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 indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a mutation. The description adds 'creates' which is consistent, but does not provide additional behavioral context such as permissions, side effects, or the structure of the consignment object.

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 extremely concise, consisting of two sentences and an Args line. It delivers the core information without any extraneous 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?

Despite annotations and schema coverage, the description lacks details about the consignment object's required fields, format of item IDs, or any constraints. A creation tool with a nested object parameter needs more guidance 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% for the single parameter, which has a generic description. The tool description adds context about 'previously saved company items' but does not elaborate on the structure or required fields of the consignment object, so it adds limited extra 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?

The description clearly states it 'creates a consignment using previously saved company items (by item ID / SKU)', which is a specific verb and resource, and distinguishes it from siblings like machship_create_consignment (general) and machship_create_consignment_with_complex_items (for complex items).

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 indicates it is for using existing saved items, which implies when not to use (if no existing items), but it does not explicitly name alternatives or exclusion criteria.

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 indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds that it creates a consignment with complex items, which is consistent with annotations. No further behavioral details (e.g., permissions, side effects) are disclosed beyond the basic create action.

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 extremely concise—two sentences, one for purpose and one for parameter. It uses an 'Args:' label for clarity and contains no redundant 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?

Given the complexity of the consignment object (nested, with dangerous goods), the description is minimal. It does not explain required fields, structure of complexItems, or return format. The openWorldHint true further signals need for clarity that is absent.

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% for the single parameter, so baseline is 3. The description merely repeats the schema description ('Consignment data with complexItems array'), adding no new meaning or constraints beyond what the schema provides.

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

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

The description clearly states it creates consignments with complex item definitions, including detailed packaging and dangerous goods data. It distinguishes from siblings like machship_create_consignment by specifying the use of a complexItems array instead of standard items.

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

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

The description implies usage when detailed packaging or dangerous goods are needed, but it does not explicitly contrast with alternatives like machship_create_consignment or machship_create_consignment_existing_items. No when-not-to-use guidance is provided.

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

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

Annotations provide basic behavioral hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description does not need to repeat those. However, the description adds no additional behavioral context such as side effects, authentication needs, or error behavior. The transparency is adequate but not enhanced.

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 very concise: two sentences plus a compact list of arguments. It is front-loaded with the purpose and structure, and every word contributes value.

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 description is adequate for a simple creation tool with no output schema. However, it lacks details on return value, error handling, and constraints (e.g., unique name). Given the presence of sibling CRUD tools and modest annotations, additional context would improve agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description merely restates parameter names and types already present in the schema without adding deeper meaning (e.g., validation rules, format, examples). It provides no extra semantic value.

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

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

The description clearly states the tool creates a new custom schema to extend Machship entities with additional fields. The verb 'creates' and resource 'custom schema' are specific, and the purpose distinguishes it from sibling CRUD operations like get, update, and delete.

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 but not explicit. The description states it creates a new schema, but does not provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions. No alternatives are 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 indicate it is a mutation (readOnlyHint=false) and not destructive. The description adds that admin access is required and the grouping constraint, but does not explain return values, error handling, or transactional behavior.

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

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

The description is concise with a clear purpose statement and a structured list of arguments. It is front-loaded but the args list is lengthy; still efficient given the complexity.

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 description lacks information about return values, success/failure responses, and potential errors. For a creation tool with nested parameters, more details about the outcome are needed.

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

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

Schema coverage is 100% with descriptions for each field. The description reiterates most parameters and adds the grouping context ('All identities must belong to the same...'), providing some additional meaning beyond the schema.

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

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

The description clearly states the action ('Create identities') and the additional assignment of companies and roles. It specifies constraints like same identityProvider and organisation, distinguishing it from other identity-related tools like update, delete, or link.

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 indicates 'Requires administrator access' and that all identities must belong to the same identityProvider and organisation. This provides context for when to use, though it does not explicitly compare to alternatives.

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

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

The description discloses that the tool creates an item, which is consistent with annotations (readOnlyHint=false). However, it does not add behavioral context beyond what annotations imply, such as required permissions, side effects (e.g., database write), or limits (e.g., SKU uniqueness). Annotations already hint at mutability and non-destructiveness, so the description adds minimal extra 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 description is very concise: one sentence stating the purpose and a bullet-like Args section. It front-loads the main action and uses minimal words, earning its place without fluff.

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 description covers the basics of what the tool does and its two parameters, but lacks important context like return value (no output schema), error conditions, prerequisites (e.g., company must exist), or behavior on duplicate SKU. For a creation tool with a nested object, more detail would be beneficial, but the description is minimally adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats parameter details from the schema but adds slight context: for companyId, 'to create item under' and for item, lists example fields like 'sku, description, weight, dimensions'. This adds value beyond the schema, but not extensively.

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

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

The title and description clearly state the tool creates a 'complex item (product/SKU with detailed packaging info)' for a company. The verb 'creates' and resource 'complex item' are specific, and it distinguishes from sibling tools like 'get_item_complex' and 'delete_item'.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'machship_create_consignment_with_complex_items' or 'machship_get_item_complex'. There is no mention of prerequisites or conditions that favor this tool over others.

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 indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it creates a draft, which is consistent. It does not disclose additional behavioral traits like permissions or limits.

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

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

The description is relatively concise, with a short explanation followed by an Args section. Some redundancy exists with the schema, but it remains efficient.

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

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

The description lacks information about the return value (created consignment), error conditions, or prerequisites. Given no output schema, this is a gap for a 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% with the 'consignment' parameter described in the schema. The description repeats the listed fields (companyId, from/to address, items, references) without adding new meaning beyond the schema.

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

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

The description clearly states the tool creates a pending consignment, a draft/staging consignment that hasn't been rated or assigned to a carrier. It distinguishes from the sibling 'create_consignment' by emphasizing the pending/draft nature.

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 notes that pending consignments can be converted to full consignments after quoting, providing context on when to use this tool. However, it does not explicitly state alternatives or when not to use it.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context that the tool performs a creation-like action but is non-destructive and intended for comparison. It clarifies the side effect (creating a quote) and the scope of returned data, which is helpful beyond the sparse annotations.

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

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

The description is concise with clear sections: action, purpose, parameter breakdown, return format, and examples. Every sentence adds value, and the structure makes it easy to parse.

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?

Despite no output schema, the description provides a sample return structure. It covers what the tool does, when to use it, what parameters are needed, and what results to expect. It is complete for its complexity and well-aligned with sibling context.

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 has 100% coverage for the single parameter 'quote' with a brief description. The tool description elaborates on the structure of the quote object (companyId, addresses, items, optional filters) and includes a Returns section with example fields. This adds substantial meaning beyond the schema.

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

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

The description clearly states that the tool creates a freight quote and returns available carrier rates. It distinguishes from siblings by positioning this tool as a comparison step before consignment creation, and explicitly contrasts with machship_create_consignment in the 'Don't use' example.

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

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

The description provides explicit guidance: 'Use this to compare carrier prices and transit times before creating a consignment' and includes a specific 'Don't use when' scenario with an alternative tool (machship_create_consignment). This leaves no ambiguity about when to invoke this tool.

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

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

The description discloses that the tool creates a quote (write operation) and returns the same format as machship_create_quote (array of rate options with cost and transit info). Annotations already indicate readOnlyHint=false, so the behavioral context is consistent. No contradictions, and the description adds useful return type information.

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 concise with a single sentence for purpose, followed by a structured Args/Returns section, and two concise usage examples. No wasted words, well-organized for quick parsing.

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

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

Given the tool's complexity (nested objects, many sibling tools), the description adequately covers what the tool does and when to use it. The return value is described by referencing machship_create_quote's output, which is sufficient. A more detailed output schema or description of the complexItems structure would increase completeness.

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 has 100% coverage but only describes the 'quote' parameter generically. The description adds meaning by stating that the quote object uses a complexItems array instead of standard items, and gives examples of when to use. This provides context beyond the schema, though more detail on the structure of complexItems would improve it.

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

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

The description clearly states the tool creates a freight quote with complex item definitions (detailed packaging, dangerous goods, serialisation data). It uses a specific verb-resource pair and distinguishes itself from sibling machship_create_quote by specifying complex items.

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 explicitly provides two 'Use when' examples: when items have dangerous goods codes, serial numbers, or non-standard packaging, and when machship_create_quote returned a validation error about item structure. This gives clear guidance on when to use this tool versus alternatives.

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 indicate destructiveHint=true. The description adds the unmanifested constraint, which is valuable beyond annotations. However, it doesn't disclose other behavioral details like reversibility, cascading effects, or authentication requirements. With annotations providing the base safety profile, the addition is useful but not comprehensive.

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

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

Two sentences plus an args list; no wasted words. Purpose is front-loaded. Every sentence contributes essential 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?

Given the destructive nature (annotations) and full schema coverage, the description covers the main behavioral constraint (unmanifested). It does not describe return values or error handling, but with no output schema, this is acceptable. Adequate for an agent to use safely.

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% for the single parameter 'ids'. The description's 'Args' section merely restates schema info without adding new semantic meaning. Baseline 3 applies as the schema already documents the parameter fully.

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?

Description clearly states 'Deletes multiple unmanifested consignments' using specific verb (delete) and resource (consignments) with a key constraint (unmanifested). It distinguishes from sibling tools like machship_delete_item or machship_delete_pending_consignments.

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

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

Explicitly states 'Cannot delete manifested consignments', providing a clear when-not-to-use condition. While it doesn't name alternative tools, the constraint is clear enough for an agent to avoid misuse.

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?

Description warns 'This is irreversible', adding context beyond annotations that already indicate destructiveHint=true. No contradictions; description aligns with and slightly extends annotations.

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

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

Two short, clear sentences. First sentence states action and parameter; second warns about irreversibility. No unnecessary words.

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

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

For a simple delete tool with one required parameter and no output schema, the description provides all necessary information: what it does, the parameter needed, and a critical warning about irreversibility.

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

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

Only one parameter (id) with schema description 'DotNet class ID'. The description restates this but adds no further meaning. Schema coverage is 100%, so description adds minimal value beyond 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?

Clearly states the verb 'Deletes' and resource 'custom schema by its DotNet class ID'. Distinguishes from sibling tools like machship_create_custom_schema and machship_get_custom_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?

No explicit guidance on when to use vs alternatives or prerequisites. The description only explains what the tool does, not when it should be chosen over other delete 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 indicate destructiveHint=true and readOnlyHint=false. Description adds 'This action is irreversible', which aligns. However, no additional behavioral traits like cascading effects or permission requirements are disclosed.

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

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

Two sentences plus a parameter listing with no fluff. Every word is necessary and efficiently conveys the purpose and key constraint.

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 destructive tool with one parameter and annotations covering safety, the description is mostly complete. It could mention return value or error conditions but is sufficient for typical use.

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 schema already describes 'ids' thoroughly. Description repeats the parameter info without adding new meaning; 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?

Description clearly states 'Delete the identities with the given IDs', which is a specific verb-resource combination. It distinguishes from sibling tools like create, get, disable, re-enable, and update identities.

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 notes the action is irreversible, implying caution, but does not explicitly guide when to use this tool versus alternatives like disable_identities (which might be reversible). No prerequisites or when-not-to-use advice is 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 indicate destructiveHint=true. The description adds 'This action is irreversible,' which clarifies permanence beyond annotations. However, it does not mention permissions, side effects (despite openWorldHint=true), or error conditions.

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 succinct sentences with a minimal argument list. Front-loaded with purpose and an important warning. No redundant or extraneous content.

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

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

For a simple one-parameter tool, the description covers the operation but lacks return value information (no output schema). Adequate but could mention success indication or error cases.

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

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

With 100% schema coverage, the description's parameter info ('companyItemId (number): The ID of the item to delete') mirrors the schema description. No additional semantic value is added beyond the schema.

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

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

The description clearly states the action ('Deletes a saved item from a company'), with a specific verb and resource. It distinguishes itself from sibling delete tools (e.g., machship_delete_consignments) by focusing on items.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites or when-not-to-use instructions. The description only states what it does, not the context for use.

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

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

The annotations already declare destructiveHint: true, so the description adds nothing beyond what is already known. It does not disclose any additional behavioral traits such as irreversibility, permission requirements, 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?

The description is very short and front-loaded, with no wasted words. However, it could add a sentence about the scope or effect without sacrificing 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?

For a simple delete operation with one parameter and no output schema, the description is minimally adequate. However, it lacks information about permanence, error conditions, or what happens after deletion.

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

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

Schema coverage is 100%, so the description of the 'ids' parameter in the tool description repeats the schema's description. No additional meaning is added beyond the schema.

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

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

The description clearly states the action 'Deletes' and the resource 'one or more pending consignments', distinguishing it from the sibling tool 'machship_delete_consignments' which deletes actual consignments.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The distinction from 'machship_delete_consignments' is implied by the name but not explicitly 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 indicate non-destructive and non-read-only behavior, which aligns with 'disable'. However, the description does not clarify reversibility or side effects beyond login prevention. With annotations present, the description adds only minimal 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?

Extremely concise: two sentences, no filler. The purpose is stated in the first sentence, making it easy for an agent to quickly understand the tool.

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

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

For a simple tool with one parameter and no output schema, the description is sufficient. It could optionally mention reversibility (e.g., 'reenable'), but is otherwise complete.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description restates the parameter but adds no new semantic information beyond what the schema already provides.

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

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

The description uses a specific verb 'disable' and resource 'identities', clearly stating the effect 'preventing them from logging in'. It distinguishes from siblings like 'reenable' and 'delete'.

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

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

No guidance on when to use this tool versus alternatives (e.g., delete identities, reenable). No mention of prerequisites, such as whether identities must be active 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 indicate readOnlyHint=false and destructiveHint=false, implying a safe write operation. The description adds 'Edits an existing...' but doesn't clarify whether it's a full replacement or partial update, or the return value. Little behavioral detail beyond annotations.

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

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

The description is short and straight to the point with one sentence and an args list. No extraneous text. Could be slightly expanded for context, but efficient.

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

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

For a write operation with no output schema, the description lacks error conditions, side effects, or response details. The agent is left guessing about the behavior and results, making it incomplete.

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

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

Schema coverage is 100% with a description for the 'location' parameter. However, the description just reiterates the schema ('Updated location data including id') without adding constraints, valid fields, or format details. 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?

The title and description clearly state the action is editing a company location. The verb 'Edits' and resource 'company location' are specific. Siblings include create and get variants, making the update purpose clear, though not explicitly differentiated.

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

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

No guidance on when to use this tool vs alternatives like create_company_location or get_company_location. No prerequisites or exclusions mentioned. The agent must infer usage 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 indicate readOnlyHint=false, so mutation is clear. Description adds the key behavioral constraint 'Cannot edit manifested consignments.' No other behavioral details like side effects or permissions.

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

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

Two sentences and an Args list with no extraneous information. Front-loaded with the core purpose and constraint.

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 mutation tool with a complex nested object parameter and no output schema, the description lacks guidance on the object structure beyond id, and does not mention the return value or any validation.

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 repeats the schema's description of 'consignment' parameter. Adds no new semantic value beyond including the 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?

Clearly states the verb (Edits), resource (consignment), and condition (unmanifested). Distinguishes from siblings by noting it cannot edit manifested consignments.

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

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

Explicitly says when to use (editing unmanifested consignments) and when not (manifested consignments). Does not name specific sibling tools but the constraint serves as guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that the tool returns 'active (in-transit)' consignments, which aligns with annotations and provides additional context. No contradictions.

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 concise: one sentence stating the tool's purpose followed by a bulleted list of parameters. No extraneous information, front-loaded with the main action.

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 tool with 5 parameters and no output schema, the description covers input parameters but does not describe the return format or provide details about response structure. Given the richness of annotations, this is adequate but leaves some gaps.

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

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

Schema description coverage is 100%, so the schema already describes each parameter. The description's 'Args' list essentially repeats the same information without adding significant meaning beyond what is in the schema.

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

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

The description clearly states the tool returns all active (in-transit) consignments for a company, using a specific verb and resource. It distinguishes this from siblings like 'get_all_consignments' or 'get_completed_consignments' by specifying the 'active' status.

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

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

The description implies usage for retrieving active consignments but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'get_all_consignments' for all statuses, 'get_completed_consignments' for completed ones). No exclusion criteria or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, reducing the burden on the description. However, the description does not elaborate on pagination behavior, default filtering, or time zone implications. It adds some context via parameter names but lacks deeper behavioral disclosure.

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

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

The description is very concise: one sentence summarizing the function, followed by a structured argument list. Every element is relevant, and the format is easily scannable.

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

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

Given the tool's complexity (9 parameters, no output schema, many siblings), the description is adequate but not complete. It explains the basic purpose and filtering options but omits details like response structure, pagination defaults, and the behavior of the filterByEtaCompletedOrDespatch parameter.

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

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

Schema description coverage is low (33%), but the description compensates by listing all parameters with brief explanations. While not exhaustive (e.g., no enum values for filterByEtaCompletedOrDespatch), it provides meaningful descriptions for each parameter, especially those missing from the schema.

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

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

The description clearly states the tool returns all consignments for a company with filtering capabilities. It uses a specific verb ('Returns') and resource ('all consignments'), and the 'all' distinguishes it from siblings like get_active_consignments or get_completed_consignments.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention scenarios where other getter tools (e.g., get_active_consignments) would be more appropriate, nor does it provide exclusion criteria.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds that it returns base64-encoded file content, which is useful beyond annotations. However, it does not disclose potential file size limits or error scenarios.

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 exceptionally concise, consisting of three short sentences with no extraneous information. It is front-loaded with the core action and return format.

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

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

Given the tool's simplicity (single parameter, no output schema, rich annotations), the description covers the essential function and return format. It could be slightly improved by mentioning typical use cases, but overall it is adequate.

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 provides full coverage (100%) with a description for the 'id' parameter. The description repeats this without adding new meaning, such as how to obtain the attachment ID or the exact expected format.

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

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

The description clearly states 'Downloads raw attachment file bytes from Machship by attachment ID', specifying the verb (downloads), resource (attachment file bytes), and method (by ID). It distinguishes from siblings like get_attachments_by_consignment_ids and get_consignment_attachments by focusing on a single attachment download, but lacks explicit 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?

No guidance on when to use this tool versus alternatives such as get_attachments_by_consignment_ids or get_consignment_attachments. There are no when-to-use, when-not-to-use, or prerequisite clarifications.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, ensuring safety. Description adds that the tool downloads a report with consignment details, but does not elaborate on additional behavioral traits.

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?

Description is concise with one clear sentence and an args block. No extraneous information, front-loads 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?

For a simple tool with one parameter and no output schema, the description covers the essential purpose and output contents. However, it could hint at the return format (e.g., binary download).

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 describes the 'id' parameter as 'Attachment ID'. The description repeats this, adding no new semantic meaning beyond what the schema provides.

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

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

Description states 'Downloads a Proof of Delivery (POD) report' with specific verb and resource, and mentions 'attachment and consignment details,' distinguishing it from sibling tools like machship_get_attachment.

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?

Description implies usage context (getting a POD report) but provides no explicit guidance on when to use this tool versus alternatives like machship_get_attachment or machship_get_consignment.

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 indicate a safe read operation (readOnlyHint, destructiveHint false, idempotent). The description adds valuable behavioral context: the zip return format and the bulk nature (up to 40 IDs). This goes beyond what annotations provide.

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

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

The description is extremely concise with two sentences, front-loading the key action and output format. Every word is informative with no fluff.

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 tool with no output schema and thorough annotations, the description provides sufficient context: what it does (download attachments), scope (up to 40 consignments), format (zip). No additional information is needed.

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 schema description fully covers the parameter, and the description only repeats the same information (array of IDs, max 40). No additional semantic meaning is added beyond the schema.

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

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

The description clearly states it downloads attachments for multiple consignments (up to 40) and returns a zip. This distinguishes it from sibling tools like machship_get_attachment (single) and machship_get_consignment_attachments (per consignment).

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

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

The description implies usage for bulk attachment downloads but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. The parameter limit is noted, but no direct comparison with 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 indicate read-only, idempotent, safe behavior. The description adds that the tool retrieves roles 'available to assign', which provides context but does not disclose additional behavioral traits like error handling or scope. Given the annotations, the description is adequate but not enhanced.

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 extremely concise with two sentences: one for the tool's purpose and one for the argument list. Every sentence is necessary and front-loaded with the core action.

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

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

Given the tool's simplicity (one required parameter, no output schema, rich annotations), the description provides sufficient context: what the tool does, what it takes, and the scope. No additional information is necessary.

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 provides 100% coverage with a description 'Company ID' for the sole parameter companyId. The tool description repeats this same information without adding further meaning, so it does not add value beyond the schema.

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

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

The description clearly states the verb 'Get' and resource 'roles' with the specific context of roles available to assign to users of a company. It is unambiguous and distinct from sibling tools, which focus on other resources like consignments, companies, etc.

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

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

The description implies when to use the tool (to retrieve assignable roles for a company) but does not explicitly state when not to use it or provide alternatives. Since there are no sibling tools for roles, the usage context is implied, but explicit guidance is missing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so agent knows it's safe and non-mutating. Description adds that it returns entries with optional status filtering, but does not address pagination, result limits, or sorting. Given annotation coverage, this is adequate.

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?

Extremely concise: two sentences and a bullet list. No redundant words, front-loaded with the core action. Every element serves a 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?

For a simple read tool with 2 parameters, the description is nearly complete: it states purpose, identifies required and optional inputs, and covers filtering. Lacks mention of return structure (no output schema) but this is minor given the tool's simplicity.

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%, providing clear descriptions for both parameters. The description reiterates parameter names and types but adds no additional semantic context like allowed status values or format of carrierInvoiceId. 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?

Describes the tool as 'Gets carrier invoice line entries with optional status filtering.' The verb 'gets' and resource 'carrier invoice line entries' clearly define its action, and the name distinguishes it from the sibling 'machship_get_carrier_invoices' which retrieves invoices themselves.

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. Context implies use when needing line entries of a carrier invoice, but no mention of alternatives like seeking invoice summaries or other filtering capabilities. Agent would rely on schema and name cues.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the 'max 100 records per call' limit, which is a useful behavioral constraint. However, it does not clarify what 'basic information' includes or if there is any pagination mechanism beyond the limit.

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

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

The description is concise: one sentence stating the purpose and limit, followed by a clear list of optional parameters. Every part is necessary, and the key info is front-loaded.

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

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

Given 4 optional parameters, no output schema, and annotations present, the description covers the main points: purpose, filter parameters, and record limit. However, it lacks details on default behavior (e.g., what happens if no filters are provided), sorting, or whether the 100 record limit implies pagination. It feels minimally adequate but not comprehensive.

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 Args section largely duplicates the schema's parameter descriptions. It adds no additional semantics beyond what the schema provides, so 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?

The description clearly states it returns basic carrier invoice information with a max 100 record limit. It uses a specific verb-resource combination. However, it does not explicitly differentiate from the sibling tool 'machship_get_carrier_invoice_entries', though the tool name itself is distinctive.

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 lists filter parameters but provides no guidance on when to use this tool versus alternatives like 'machship_get_invoice_by_document_number' or 'machship_get_posted_invoices'. There is no mention of when not to use it or recommended contexts.

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 indicate readOnlyHint and idempotentHint, so the description adds limited behavioral context. It notes the return of a PDF but does not disclose any additional traits such as authentication requirements or file size limits.

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

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

The description is extremely concise with two sentences and a short args list. No unnecessary words, and the main purpose is front-loaded. Every word earns its place.

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

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

Given the simple tool with one parameter and no output schema, the description adequately states what the tool does and what it returns. It could mention the file format or that the response is a binary PDF, but the phrase 'commercial invoice PDF' is 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?

The parameter consignmentId is documented in the schema with the same description. The description adds no extra meaning beyond the schema, which already has 100% coverage. Baseline of 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?

The description clearly states the tool returns the commercial invoice PDF for a consignment, using a specific verb and resource. This distinguishes it from other PDF retrieval tools like machship_get_dangerous_goods_pdf or machship_get_consignment_label_pdf.

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 mentions 'used for international shipments,' providing some context for when to use, but it does not explicitly differentiate from sibling PDF tools or state when not to use it. No alternatives 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=true, destructiveHint=false, etc. The description adds hierarchical filtering behavior, output format details, error codes (401, 403), and return object structure. No contradiction.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Slightly lengthy but every section is informative and adds value.

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

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

Given the tool's simplicity (2 optional parameters, no output schema but description includes return structure), the description covers usage, outputs, errors, and examples thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: hierarchical filtering for atOrBelowCompanyId, default for response_format, and examples. This is meaningful beyond the schema.

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

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

The description clearly states the tool returns all companies accessible to the user and specifies the structure of returned objects. It distinguishes from siblings by mentioning that for carrier/service info, one should use machship_get_company_carriers instead.

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

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

Includes explicit 'Use when' and 'Don't use when' examples with an alternative tool. Also covers error handling with specific HTTP status codes and suggested fixes.

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

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

Annotations cover read-only, non-destructive, idempotent, open-world. Description adds return structure detail, but no further behavioral traits. No contradiction.

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, then Args, Returns, Examples. No unnecessary words; every sentence adds value.

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 2 parameters and no output schema, description provides detailed return structure example and usage context, making it complete for selecting and invoking the 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 covers 100% parameters with descriptions. Description lists same info and adds return structure context, but no new parameter semantics beyond schema.

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

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

The description clearly states it returns carriers, accounts, and services for a company. Examples show when to use, differentiating from sibling tools like get_companies.

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

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

Explicit guidance: call before creating consignments/quotes, and don't use for company list (use get_companies instead). Examples help.

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 provide readOnlyHint, destructiveHint, idempotentHint. Description adds no further behavioral traits like error handling or permissions. With annotations present, description's minimal addition is acceptable but not enhanced.

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-line description with front-loaded purpose and clear parameter listing. No extraneous words.

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

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

No output schema, so description should hint at return structure. It says 'returns details' but omits what fields. Adequate for a simple read tool, but could be more 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 coverage is 100% and description rephrases parameter definition ('Company location ID') without adding meaning. Description adds no value beyond 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?

Description clearly states verb 'Returns details for a single company location' and specifies resource types (warehouse, store, depot). Distinguishes from siblings like get_company_locations (plural) and create/edit variants.

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?

Implicit that this tool is for fetching a specific location by ID, but does not explicitly contrast with siblings like get_company_locations for listing or state when to choose this over alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds minor context (locations types: warehouses, stores, depots) but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

The description is extremely concise: two sentences stating the purpose and listing the argument. No unnecessary words or repetition. It is front-loaded with the core functionality.

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

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

For a simple read tool with one parameter and no output schema, the description is mostly complete. However, it fails to describe the return format or any pagination behavior, leaving the agent without information on what the response structure looks like. Given the low complexity, a 3 is adequate.

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% as the schema describes the single parameter 'companyId' with description 'Company ID'. The description repeats this exactly without adding extra meaning, format, or examples. 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?

The description clearly states it returns 'all locations' for a given company, specifying the resource (locations) and action (return). It distinguishes from the sibling tool 'machship_get_company_location' which likely returns a single location, by explicitly using 'all'.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'machship_get_company_location' or 'machship_search_locations'. It does not mention prerequisites, when not to use, or any context for selection.

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

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

Annotations already cover readOnly, destructive, idempotent, and openWorld hints. The description adds a useful behavioral constraint (max 2000 results), but does not describe return format or pagination details beyond that.

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

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

Two sentences plus a clear bullet list, front-loaded with core purpose, no redundancy or fluff.

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 description is complete for a read-only query with annotated safety traits, but lacks details on the return structure (e.g., list of consignment objects) since no output schema is provided.

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 75%. The description repeats schema descriptions for 3 params and adds a brief description for includeChildCompanies (missing in schema). No additional semantic detail beyond labels.

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

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

The description clearly states the verb 'returns' and the resource 'completed (delivered) consignments' with a date range and max 2000 results, distinguishing it from siblings like get_active_consignments or get_all_consignments.

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

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

The description implies usage for retrieving delivered consignments within a date range, and the max results hint at pagination considerations, but lacks explicit when-to-use vs alternatives like get_active_consignments.

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 indicate readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the description's behavioral disclosure is not strictly required. The description adds no further behavioral details (e.g., authentication, rate limits, or what 'full details' entails), but is consistent 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?

The description is extremely concise: one sentence summarizing the function followed by a clear list of parameters. No unnecessary words, and the main purpose is front-loaded.

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

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

For a simple read tool with three well-documented parameters and clear annotations, the description is nearly complete. The only minor gap is lack of output schema, but the phrase 'full details' adequately conveys the return value's scope.

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 itself fully documents each parameter. The description repeats parameter info without adding new meaning beyond the schema, earning baseline 3.

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

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

Description clearly states 'Returns full details for a single consignment by ID', which is a specific verb-resource pair that effectively distinguishes from sibling tools that retrieve multiple consignments or use other criteria.

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 guidance on when to use this tool versus alternatives like machship_get_consignments_by_ids or machship_get_consignment_by_pending_id. The usage is implied by the name and description, but there is no direct contrast or exclusion.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the agent knows this is a safe, non-destructive operation. The description adds that it returns only metadata, not file contents, which is useful context. However, it does not elaborate on any side effects or limitations beyond what annotations convey.

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

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

The description is extremely concise: two sentences that front-load the core purpose and immediately clarify that it returns metadata only. No extraneous words or fluff.

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

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

For a simple read-only metadata retrieval with one parameter and no output schema, the description covers the essential purpose and parameter. It could optionally list metadata fields (e.g., filenames, sizes) but is sufficient given annotations and tool simplicity.

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 provides a 100% covered parameter 'consignmentId' with description 'Consignment ID.' The tool description repeats this information without adding new meaning or constraints. Baseline is 3 for high schema coverage.

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

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

The description clearly states 'Returns attachment metadata (not file contents) for a consignment,' which specifies the verb (returns), resource (attachment metadata), and scope (for a consignment). It distinguishes from sibling tools like machship_get_attachment (which returns file contents) and machship_upload_attachments.

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 hints at usage by noting it returns metadata not file contents, implying that for file contents one should use another tool. However, it does not explicitly state when to use this tool versus alternatives like machship_get_attachments_by_consignment_ids or machship_get_attachment, leaving room for ambiguity.

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 (readOnlyHint=true, idempotentHint=true) indicate a safe read operation. The description adds behavioral insight by noting that the consignment details are retrieved 'if it exists', implying possible null result. This adds value beyond annotations.

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

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

The description is short and front-loaded with the purpose. However, the Args section is redundant given the schema, which slightly reduces conciseness. Still 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the essential information: what it does, the condition (if exists), and the parameter. No further details are needed for a complete understanding.

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% (the only parameter 'id' is fully described in the schema). The description's Args section merely repeats the schema information without adding new meaning, so no additional value for semantics.

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

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

The description clearly states 'Get consignment details' using a specific resource (pending consignment ID that has been transformed into a consignment). It distinguishes from sibling tools like machship_get_consignment (which uses a consignment ID) and machship_get_pending_consignment (which gets pending consignment).

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 explains that the tool is for getting consignment details from a pending consignment ID that has been linked, but it does not explicitly state when to use this tool over alternatives (e.g., machship_get_consignment_by_ids or machship_get_pending_consignment). Usage context is implied but not explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by explaining the specific output (settings with required fields, defaults) and the default behavior for the companyId parameter. It does not contradict annotations and provides useful context beyond what annotations offer.

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 extremely concise: two sentences plus a parameter list. It front-loads the core purpose and provides essential details without any fluff. Every sentence earns its place.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool returns, the parameter, and default behavior. No gaps remain for the agent to correctly invoke and understand the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by stating that the companyId defaults to the authenticated company, which is additional semantic information that helps the agent understand parameter 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 clearly states the action ('returns'), the resource ('settings and defaults needed for creating consignments'), and the scope ('for a company'). It effectively distinguishes this tool from the many other 'get_consignment' siblings by focusing specifically on creation settings.

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

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

The description implies the tool is used for retrieving settings before creating a consignment, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or when not to use it. The context provides enough differentiation from siblings to infer usage, but lacks direct 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 indicate a safe read operation (readOnlyHint=true). The description adds that the output is specially formatted for cloning, which provides behavioral context beyond the annotations. No contradiction.

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

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

Two sentences plus an args list, front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

No output schema, but the description clarifies the output format (passable to createConsignmentWithComplexItems). Given the simple one-parameter tool and annotations, this is adequately complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the schema's parameter description ('Consignment ID') with minor wording change, adding no significant new 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?

Clearly states the verb 'Get', the resource 'consignment', and the specific purpose 'in a format that can be passed directly to the createConsignmentWithComplexItems endpoint to create a copy', distinguishing it from sibling get-consignment tools.

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

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

Explicitly describes when to use this tool (to create a copy via the createConsignmentWithComplexItems endpoint). Does not explicitly mention when not to use or alternatives, but the use case is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds minimal incremental value by specifying PDF format, but does not disclose edge cases like missing consignment IDs or response size limits. With annotations present, a 3 is appropriate.

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 concise: two sentences, front-loading the result format. No wasted words, but could be slightly more 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?

Simple tool with one parameter, annotations, and no output schema. Description is adequate but does not clarify potential variations (e.g., whether base64 or bytes depends on some context). Lacks completeness for a full understanding.

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

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

Schema coverage is 100% with one integer parameter. The description repeats the parameter name and type ('consignmentId (number): Consignment ID') without adding extra meaning beyond the schema. Baseline 3 is correct.

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

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

The description clearly states it returns a consignment label as a PDF, specifying the format (base64 or file bytes). It distinguishes from sibling tools like machship_get_item_label_pdf by targeting consignment labels specifically.

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

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

No guidance on when to use this tool versus other label retrieval tools (e.g., machship_get_item_label_pdf, machship_get_manifest_label_pdf). The agent receives no context about prerequisites or alternative choices.

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?

Description adds context beyond annotations by stating it returns notes including types like internal comments and delivery instructions. Annotations already declare readOnlyHint=true and idempotentHint=true, so no contradiction. Somewhat lacking details on ordering or pagination.

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

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

Description is brief and front-loaded with purpose. Slight redundancy in repeating param info, but overall concise and well-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?

For a simple read-only tool with one param and no output schema, the description adequately specifies return content. Could mention error handling or if empty notes returned.

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

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

Schema coverage is 100%, so baseline is 3. Description merely repeats schema's param description ('Consignment ID') without adding extra semantic meaning or format details.

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

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

The description uses specific verb 'Returns' and resource 'all notes attached to a consignment', with examples of note types. Clearly distinguishes from many sibling get_*_consignment tools.

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

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

No guidance on when to use this tool vs alternatives. Does not mention that other tools like 'machship_get_consignment' might be more appropriate for core consignment data.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'without downloading', which reinforces non-destructive behavior. However, it lacks details on authentication requirements, rate limits, or potential side effects beyond what annotations cover.

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

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

The description is two sentences long, front-loaded with the purpose, and includes a clear argument list. Every sentence earns its place without redundancy or unnecessary 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?

For a metadata retrieval tool with no output schema, the description adequately lists the returned fields (name, size, URL). Combined with the informative annotations and simple parameter, no additional information is necessary for an agent to understand the tool's behavior.

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

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

The input schema describes consignmentId as 'Consignment ID' with type integer. The description restates the same information in Args without adding extra context (e.g., format, source, or validation rules). Since schema coverage is 100%, the description adds no additional 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?

The description clearly states the tool returns file metadata (name, size, URL) for the consignment label PDF without downloading it. This specific verb+resource combination effectively distinguishes it from sibling tools like 'machship_get_consignment_label_pdf'.

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

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

The description implies usage for getting metadata instead of downloading, but does not explicitly state when to use this tool versus alternatives. No when-not-to-use or alternative names are provided, leaving the agent to infer context 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 already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that it limits results to a max of 10, providing extra behavioral context. No contradictions.

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 extremely concise, using a single sentence for the purpose and a bullet for the argument. No redundant 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?

Given the simplicity of the tool (one parameter, no output schema), the description is largely complete. It covers the key constraint (max 10) and the nature of the IDs. It could mention what happens if IDs are not found, but this is a minor gap.

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

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

The description defines the parameter as an array of carrier consignment IDs with a max of 10, clarifying that these are 'carrier's own consignment/tracking ID'. This adds context beyond the schema's description, which only says 'Carrier consignment IDs (max 10)'.

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

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

The description clearly states it finds consignments by the carrier's own consignment/tracking ID. It specifies the resource and the lookup key, but does not explicitly differentiate from sibling tools like get_consignments_by_ids or search_consignments.

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 mentions a max limit of 10 per request, which is a constraint, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when you have a carrier ID vs. internal ID). Usage is 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 readOnlyHint and idempotentHint, so the safety profile is clear. The description adds the batch size limit (max 100) but does not disclose details about return format, error handling, or authentication requirements. The statement 'Returns details' is vague.

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 extremely concise, consisting of two short sentences with no fluff. The key information (purpose and parameter) is front-loaded. Every word contributes value.

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

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

Given the tool's simplicity (one parameter, no output schema, no nested objects) and the strong annotations, the description provides sufficient context for a basic read operation. It could mention that the output matches individual consignment details, but the current level is adequate for agent understanding.

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 has 100% coverage (the 'ids' parameter is fully described in the schema as an array of integers with min/max). The description merely restates the schema comment, adding no new semantic information about the parameter beyond what is already in the schema.

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

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

The description clearly states the tool returns details for multiple consignments by their IDs, distinguishing it from sibling tools like 'get_consignment' (single) and other batch retrieval tools by specifying the use of consignment IDs directly. The max limit of 100 further clarifies scope.

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

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

The description implies usage when a list of consignment IDs is available, but it lacks explicit guidance on when to use this versus alternatives like 'get_consignments_by_carrier_id' or 'search_consignments'. No when-not-to-use or alternative recommendations are provided.

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

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

The description adds a behavioral trait beyond annotations: the maximum batch size of 100 consignments. Annotations already cover safety (readOnly=true, etc.), so the description provides complementary 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 description is extremely concise, with two sentences and a bulleted arg list. No unnecessary words, and all information is front-loaded.

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

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

For a simple batch retrieval tool with no output schema, the description is mostly complete: it explains the purpose, the parameter, and a key constraint. However, it does not describe the return format (e.g., array of consignments).

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

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

The description repeats the schema information for the single parameter 'ids' (type, min/max). Since schema coverage is 100%, the description adds minimal new 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?

The description clearly states the verb 'Get', the resource 'consignment details', and the lookup method 'using Pending Consignment IDs'. It distinguishes from siblings by specifying 'multiple consignments' and 'batch', differentiating it from the single-consignment sibling tool.

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

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

The description implies usage for batch retrieval by pending IDs and sets a clear context (max 100 consignments), but does not explicitly mention when not to use it or provide alternatives.

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 indicate read-only, non-destructive, idempotent, and open-world behaviors. The description adds a critical behavioral constraint ('Max 10 per request') that is not captured by annotations, increasing transparency. No contradictions found.

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 extremely concise: two lines for the main description and one line for the argument. Every sentence adds value, and the key information is front-loaded. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers the purpose, constraint, and parameter format. The existing annotations and schema provide sufficient context, and the description fills the gap by adding the request limit.

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 covers 100% of parameters, and the description essentially restates the schema ('references (string[]): Array of Reference 1 values (max 10)'). No additional semantics beyond the schema are provided, so the baseline score of 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?

The description clearly states the action ('Finds'), resource ('consignments by their Reference 1 field'), and a key constraint ('Max 10 per request'). It effectively distinguishes this tool from siblings like get_consignments_by_ids and get_consignments_by_reference2.

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

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

The description implies usage when you have Reference 1 values but does not explicitly state when to use this tool over alternatives or provide exclusions. Among many similar fetch tools, no guidance is given on differentiation.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds the maximum request limit but does not elaborate on error handling, pagination, or response behavior.

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

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

The description is brief with two sentences and an inline args list. It is well-structured and contains no unnecessary information, but could benefit from more explicit formatting.

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

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

Given the low complexity (one parameter, no output schema), the description provides the essential operation and constraint. However, it lacks details on return values or potential errors, which would be helpful without an output schema.

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

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

Schema coverage is 100% with a description that already explains the parameter. The description ('Array of Reference 2 values (max 10)') adds no new meaning beyond the schema.

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

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

The description uses a specific verb 'Finds' and resource 'consignments by their Reference 2 field', clearly distinguishing from sibling tools like those for reference1 or IDs.

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 states the max limit of 10 references but does not provide explicit guidance on when to use this tool versus alternatives like search_consignments or other get methods.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the output type (statuses) and optional date filtering. However, it does not disclose error behavior for invalid IDs, rate limits, or what 'statuses' entails beyond tracking/delivery.

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 extremely concise: one sentence for purpose followed by two parameter descriptions. No wasted words, and the essential information is front-loaded. Every sentence serves a clear 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?

Given the simple 2-parameter tool with no output schema, the description adequately covers the inputs and basic behavior. It doesn't explain the return format (e.g., array of status objects), but for a read-only tool with strong annotations, it is sufficiently 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 coverage is 100%, the descriptions in the description duplicate the schema descriptions (e.g., 'Consignment IDs', 'Only return statuses since this UTC datetime (ISO 8601)'). No additional semantics are provided beyond what the schema already conveys.

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

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

The description clearly states the tool 'returns tracking/delivery statuses for a batch of consignments', using a specific verb and resource. It distinguishes itself from sibling tools like 'get_consignment' (returns single consignment details) and 'get_consignments_by_ids' (returns consignment objects) by focusing on statuses and batch processing.

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

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

The description implies batch use via 'batch of consignments' and the 'ids' parameter, but it does not explicitly state when to use this tool versus alternatives like 'get_consignment' or 'update_consignment_statuses'. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds no extra behavioral context (e.g., what happens if the ID does not exist). With annotations covering safety, the description is adequate but not enhanced.

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 (two sentences) and direct, but the second sentence redundantly restates parameter details already present in the schema. It could be more efficient by omitting the parameter list.

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 retrieval tool with good annotations and a single parameter, the description is mostly sufficient. However, it does not mention what the response contains (e.g., the full schema object), which could be improved for completeness.

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 repeats the parameter info ('id (string): The DotNet class ID of the schema') without adding new semantics. 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 clearly states the action ('Returns a specific custom schema by its DotNet class ID'), specifying both the verb and the resource. It distinguishes from sibling tools like 'machship_get_custom_schemas' (plural), which retrieves all schemas.

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

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

No explicit guidance on when to use this tool versus alternatives, such as when to use 'machship_get_custom_schemas' instead. The context for use is implied but not stated.

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

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

Annotations already declare `readOnlyHint=true`, `destructiveHint=false`, and `idempotentHint=true`, so the agent knows this is safe and idempotent. The description adds minimal behavioral context by explaining that it returns all custom schemas and what they are, but does not disclose anything beyond what annotations imply (e.g., no mention of pagination or output format). With annotations handling most of the burden, a score of 3 is appropriate.

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

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

The description is two sentences, front-loading the primary purpose (returns all custom schemas) and then clarifying the domain (what custom schemas are). Every sentence earns its place with no redundant or extraneous 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?

Given the tool has no parameters, no output schema, and the annotations are rich, the description adequately conveys the tool's role. It defines the output concept (all custom schemas) and the entity type. Minor improvement could mention that no filtering or pagination is available, but the description is sufficient for an agent to understand when to select this tool.

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

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

The tool has zero parameters and schema coverage is 100%. The description adds meaning by explaining what a custom schema is, which helps the agent understand the return value. Since there are no parameters to document, a baseline of 4 is justified.

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

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

The description clearly states it returns all custom schemas, defines what custom schemas are, and the name `get_custom_schemas` (plural) distinguishes it from the singular `get_custom_schema` sibling. This gives the agent a precise understanding of the tool's function.

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

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

No guidance is provided on when to use this tool versus alternatives like `get_custom_schema` (singular) or other get-* tools. The description assumes the agent knows to choose this when needing all schemas, but no explicit context or exclusion criteria 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 indicate read-only, idempotent, non-destructive behavior. The description adds no additional behavioral context (e.g., prerequisites like consignment having dangerous goods, or that PDF is generated). Does not contradict 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?

Very short and front-loaded; one sentence plus a parameter list. Efficient but could be slightly improved with a more structured format.

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

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

For a simple read-only tool with one parameter and no output schema, the description is mostly complete. It lacks mention of error cases or return format, but overall 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 already describes the single parameter (consignmentId) with full coverage. The description merely repeats the schema info with no added meaning beyond what the schema provides.

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

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

The description clearly states 'Returns the dangerous goods declaration document PDF for a consignment,' which is specific to the resource (dangerous goods PDF) and distinguishes it from sibling tools like get_attachment or get_commercial_invoice_pdf.

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

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

No guidance on when to use this tool versus alternatives. With many sibling PDF tools, explicit context for when this is appropriate is missing.

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 provide readOnly, destructive, idempotent, and openWorld hints. The description adds that it returns metadata, which is appropriate, but does not detail the metadata fields, leaving partial transparency for a tool with no 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?

Two sentences: first sentence states purpose with key differentiation, second lists the parameter. No redundancy, front-loaded, and efficient.

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

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

For a simple one-parameter read-only tool, the description is mostly complete. Minor gap: does not specify what 'file metadata' includes, which could be clarified given no output schema.

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

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

Schema coverage is 100% and the description restates the parameter without adding new meaning; baseline score of 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?

The description clearly states the verb 'Returns', the resource 'file metadata for the dangerous goods declaration PDF', and the key qualifier 'without downloading it', effectively distinguishing it from sibling tool machship_get_dangerous_goods_pdf.

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 'without downloading it' implies when to use this tool versus the download variant, but does not explicitly specify alternatives or conditions, leaving some room for ambiguity.

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 provide readOnlyHint, destructiveHint false, idempotentHint, and openWorldHint, indicating a safe read operation. The description adds no additional behavioral traits (e.g., pagination, rate limits, response structure) beyond what annotations and schema provide. With annotations covering the safety profile, a score of 3 is appropriate.

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 concise: three sentences plus a structured Args list. The first sentence states purpose directly. Every sentence adds value. The format is front-loaded and 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?

Given the tool has 3 parameters and no output schema, the description adequately covers the purpose, required access, and parameter details. It could optionally mention the return type or pagination, but the information provided is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% (all 3 parameters are described in the schema). The description repeats the parameter names and types, adding only minor clarity (e.g., labeling 'onlyUnlinkedIdentities' as optional). This does not significantly enhance understanding beyond the schema, so baseline 3 is correct.

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

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

The description clearly states the tool retrieves all identities owned by an organisation, including details on linked companies. This specific verb-resource-scope combination distinguishes it from sibling tools like machship_get_identity (single identity) and machship_create_identities.

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 mentions a prerequisite: 'Requires administrator access to the organisation.' It implicitly indicates use for listing identities, but does not explicitly state when to use this tool over alternatives like machship_get_identity or machship_get_identity_providers_for_organisation. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no additional behavioral context (e.g., authentication requirements, error behavior). It is consistent but not additive.

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 very concise with one clear sentence plus a parameter list. No unnecessary words. However, it could be slightly more informative without being verbose.

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 simple with one parameter and no output schema. The description is minimal but sufficient for a basic retrieval operation. However, it lacks any indication of what the response contains (e.g., identity details), which could be helpful for an AI agent.

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 already describes the 'id' parameter with 100% coverage. The description only repeats the parameter name and type, adding no new meaning beyond what the schema provides. 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?

Description clearly states 'Get the identity with the given ID.' It uses a specific verb ('Get') and resource ('identity'), and the singular form distinguishes it from sibling tools like machship_get_identities (list) and machship_update_identity (update).

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

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

No guidance on when to use this tool versus alternatives (e.g., machship_get_identities for listing, machship_update_identity for updating). The description does not provide context for selecting this tool over 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 provide strong behavioral cues (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds only that it retrieves by ID, which is consistent but adds no extra behavioral context (e.g., what happens if ID not found).

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?

Extremely concise: two sentences that front-load the purpose and list the parameter. No redundant phrases.

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

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

Given the extensive sibling list, the description is minimal. It omits any mention of return value or error handling. While the schema is rich, the tool would benefit from stating that it returns a single identity provider object.

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 schema covers 100% of parameters with a description identical to the description's mention. The description does not add any new meaning beyond the schema, so baseline score 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 clearly states 'Get a specific identity provider by ID', which is a specific verb+resource. It distinguishes from sibling list tools (e.g., machship_get_identity_providers_for_company) by focusing on a single provider retrieval, though it could explicitly differentiate.

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

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

No guidance on when to use this tool versus alternatives. With many similar identity-related tools (e.g., machship_get_identity, machship_get_identity_providers_for_company), the description should hint at appropriate contexts but does not.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safe read nature is clear. However, the description adds no additional behavioral context beyond what annotations imply. It does not discuss potential errors, rate limits, permissions, or the shape of the response. With annotations present, the description fails to add 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 description is very short: one sentence plus an args list. It is not verbose, but the args list is redundant given the schema. However, it is still appropriately sized and front-loaded. It could be more concise by removing the args list, but it earns its place.

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

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

For a simple get tool with one parameter and no output schema, the description is incomplete. It does not mention the return format (e.g., list of identity providers), any ordering, or pagination. The annotations cover safety, but the description fails to provide enough context for an AI to fully understand the tool's behavior.

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

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

Schema coverage is 100%, and the description merely restates the parameter name and type ('companyId (number): Company ID'). It adds no new meaning beyond what the input schema already provides. Baseline 3 is appropriate as 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 clearly states the purpose: 'Get all identity providers associated with a specific company.' It uses a specific verb and resource. However, it does not differentiate from sibling tools like 'machship_get_identity_providers_for_logged_user' and 'machship_get_identity_providers_for_organisation', which have very similar names and purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or contrast with similar tools. Given the existence of sibling tools for different contexts (logged user, organisation), this is a significant omission.

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, destructiveHint, idempotentHint, and openWorldHint, so the description adds minor value by confirming it returns all identity providers and requires no parameters. No contradictions.

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 extremely concise: two sentences, no wasted words. First sentence states purpose, second states no parameters. Perfectly structured for a simple tool.

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

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

For a zero-parameter, read-only tool with no output schema, the description adequately covers what it does and its scope. All necessary information is provided for the agent to 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?

With no parameters, the schema provides all information. The description restates 'No parameters required', which is clear but does not add meaning beyond the schema. Baseline for 0 params is 4.

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