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

With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only says 'add', implying a mutation, but it does not disclose side effects, whether shipments are removed from other batches, idempotency, validation rules, or potential failure modes. The description offers no information about the effects of the operation beyond the basic verb.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the verb and clear object structure, making it easy to parse quickly. Every word contributes to the meaning 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?

The tool has no output schema and no annotations, so the description must compensate. It does not explain what happens after adding (e.g., return value, batch state changes), nor does it provide context about batch lifecycle or constraints (e.g., whether shipments must be in a certain status). The brief description is insufficient for an agent to fully understand the operation's implications.

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

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

Schema description coverage is 100%, with both batch_id and shipment_ids having clear descriptions. The tool description adds little beyond the schema: 'one or more shipments' merely paraphrases the array parameter. Since the schema already documents the parameters, the description provides no additional semantic value, so the 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 action ('Add') and the resource ('shipments to a batch'), with the scope of 'one or more' explicitly mentioned. This is a specific verb+resource statement that naturally distinguishes from sibling tools like remove_from_batch and create_batch.

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 situations where this tool is appropriate, prerequisites, or contrast with related operations like chitchats_remove_from_batch or chitchats_create_batch. Any usage context is only implied by the verb 'add'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key trait: this is an async operation, and advises checking shipment status afterward. However, it omits other important details such as side effects (financial transaction), failure modes, or whether the shipment must be in a particular state. The disclosure is partial.

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 short sentences, front-loaded with the core action and followed by a critical behavioral note. Every sentence serves a purpose, and there is no redundant or filler 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 with no output schema and no annotations, the description covers the essential action and the important async follow-up. It lacks explicit prerequisites or success/failure details, but given the tool's simplicity, the description is sufficiently complete for basic usage.

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 already describes the only parameter 'id' as 'Shipment ID' with 100% coverage. The description adds no extra parameter semantics beyond the schema, 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 states a specific action: 'Purchase postage for a shipment.' This clearly identifies the verb (purchase) and resource (postage for a shipment), and distinguishes it from siblings like get_rates or create_shipment. The async note adds a unique behavioral trait that further disambiguates it.

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

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

The description implies usage: you have a shipment and need to purchase postage. It provides a follow-up instruction ('check shipment status after') but does not explicitly mention when to use this tool versus alternatives, nor does it give exclusions or prerequisites. Guidance is minimal but not misleading.

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 annotation readOnlyHint=true already covers safety, so the bar is lower. The description adds the optional status filtering context but does not disclose other behaviors like return format or aggregation logic. This is adequate but not rich.

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

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

The description is a single concise sentence that front-loads the verb and object. It contains no filler and every word contributes to clarity.

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 optional parameter, no output schema, and full schema coverage, the description is sufficiently complete. It conveys the purpose and the only filter, and the readOnly annotation covers safety. Sibling context provides additional orientation.

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 already fully documents the only parameter (status) with an enum and description. The description's 'optionally by status' adds no new meaning, so the baseline 3 applies because 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 'Get count of batches' with an optional status filter, making the verb and resource explicit. It naturally distinguishes from sibling tools like chitchats_count_shipments and chitchats_list_batches.

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

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

No explicit guidance is given on when to use this tool over alternatives. It implies a quick aggregate count but does not mention exclusions or refer to related tools like list_batches or count_shipments.

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 readOnlyHint annotation already declares the operation safe. The description adds the optional status filter context, but no additional behavioral details like rate limits or response format. It is consistent with annotations and adds some context, but not rich.

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

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

A single clear sentence with no filler. Perfectly front-loaded and 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?

For a simple count tool with one optional parameter and a readOnly annotation, the description is sufficient. The return type (a count) is implicit in the verb, and the optional filter is mentioned. No output schema is needed for such a simple operation.

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

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

Schema description coverage is 100%, so baseline is 3. The description's 'optionally filtered by status' adds no new meaning beyond the schema's filter description; it merely restates what the schema already says.

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 'get a count' with resource 'shipments', clearly distinguishing it from list_shipments and get_shipment. It conveys exactly what the tool returns and is not a tautology.

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 count is needed rather than a list—but does not explicitly mention alternatives or exclusions. It provides no guidance on when not to use it, so it stops at implied usage.

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

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

With no annotations, the description must bear the full burden of behavioral disclosure. It only states the creation intent and does not mention whether the batch starts empty, what the response contains, or any prerequisites 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 a single concise sentence that front-loads the action and purpose, containing no wasted words or irrelevant details.

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 creation tool with one optional parameter and no output schema, the description is adequate but could be more complete by noting that the batch is created empty and shipments can be added later via add_to_batch.

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 already covers the single parameter with its own description ('Batch name/description'), so the baseline of 3 applies. The tool description adds no additional meaning for the parameter.

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

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

The description clearly states the action ('Create a new batch') and its purpose ('to group shipments for drop-off'), which distinguishes it from sibling batch tools like list, get, delete, add, and remove.

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 given on when to use this tool versus alternatives like add_to_batch or remove_from_batch. The description simply states what it does without context or exclusions.

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

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

With no annotations, the description must disclose behavioral traits, but it only states the high-level action. It does not clarify side effects (e.g., whether the shipment is charged immediately), prerequisites, or response format. This is insufficient for a create operation with 22 parameters.

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

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

The description is a single, front-loaded sentence that efficiently communicates the core function. No wasted words, though it may be overly terse for the tool's 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?

Given the tool's complexity (22 parameters, no output schema), the description lacks important context such as required vs optional fields, response behavior, and when to use alternative tools. It does not explain what happens after creation (e.g., returns shipment details, generates labels), leaving significant gaps for the 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 provides 100% coverage with descriptions for all parameters. The description adds minimal grouping (address, dimensions, order reference) but does not provide additional semantic meaning beyond the schema. Baseline is 3.

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

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

The description clearly states the tool's function: 'Create a new shipment' with a brief summary of the parameters (recipient address, package dimensions, optional order reference). It distinguishes the tool from siblings like chitchats_list_shipments or chitchats_delete_shipment by identifying the specific create action.

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

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

The description implies usage for creating shipments but provides no explicit when-to-use or alternative guidance. It does not mention that bulk creation should use chitchats_create_batch or that rates can be fetched with chitchats_get_rates, leaving the agent to infer context.

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 include destructiveHint: true, which already flags the mutating nature. The description adds valuable behavioral context beyond the annotation by specifying the 'empty batch' precondition and the limitation on batches with shipments. It does not contradict annotations and discloses a key operational constraint.

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: two short sentences that immediately state the action and the key restriction. Every word earns its place, with no redundant phrasing 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 simple tool with one parameter, no output schema, and a destructive annotation, the description adequately covers the essential context for selection and invocation. It explains the primary prerequisite (empty batch). It could mention what happens if a non-empty batch is attempted, but given the tool's simplicity, current detail 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 input schema has 100% coverage: the single parameter 'id' is described as 'Batch ID'. The description does not add additional parameter-level details, but since the schema fully documents the parameter, a 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 'Delete an empty batch' with a specific verb (delete) and resource (batch), and distinguishes it from other operations by adding the 'empty' constraint. This differentiates it from sibling tools like chitchats_delete_shipment and batch modification 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?

The description gives clear usage context by explicitly stating that only empty batches can be deleted, and that batches with shipments cannot be deleted. This implicitly guides the agent to use other tools (like remove_from_batch) for non-empty batches, though it doesn't name an explicit alternative.

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 the description adds valuable context: the tool only works on unpaid shipments. This goes beyond the annotation by explaining a key limitation. It does not mention side effects or error behavior, but given the low complexity, it is sufficient.

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 short sentences that immediately convey the core action and the key constraint. Every word earns its place, and the structure is clear and 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 single-parameter tool with no output schema, the description, combined with the annotation and schema, provides all necessary information. The condition about unpaid shipments is critical and clearly stated, making the tool complete for its intended 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?

The input schema has 100% coverage for the single parameter 'id' with description 'Shipment ID to delete'. The tool description does not add further semantic detail about the parameter beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the action 'Delete' with resource 'shipment', and specifies the scope as 'unpaid shipment'. It distinguishes this from related tools by adding the constraint that only shipments without purchased postage can be deleted, making the purpose unambiguous.

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

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

The description provides clear context on when to use this tool: for deleting unpaid shipments only. It implicitly excludes paid shipments but does not explicitly mention alternatives like refund_shipment or buy_postage. Still, the condition is specific enough for correct usage.

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 readOnlyHint annotation already indicates a safe read operation, and the description does not add any behavioral context beyond the basic retrieval action. No extra detail about response format, pagination, or side effects is provided, which is acceptable given the annotation coverage.

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

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

The description is a single sentence with no wasted words, front-loading the verb and resource. It earns its place completely.

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 single-parameter read operation with a readOnlyHint annotation and no output schema, the description is adequately complete. It clearly states the input and action, though it could optionally elaborate on what 'details' are returned, but this is not a significant gap given the 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 coverage is 100% for the single 'id' parameter described as 'Batch ID'. The description adds nothing beyond the schema; the phrase 'by ID' simply restates the parameter's purpose. The baseline of 3 applies because the schema fully documents the parameter.

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

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

The description uses a specific verb ('Get') and the resource ('details of a specific batch by ID'), clearly distinguishing it from sibling list_batches and get_shipment tools. The scope is unambiguous.

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

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

The description implies usage for retrieving a single batch by ID, but it does not explicitly state when to prefer this over alternatives or mention any exclusions. Context from the tool name and siblings provides some guidance, but the description itself gives no direct comparison.

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

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

The readOnlyHint annotation already marks the operation as read-only. The description adds beyond that by specifying the return types (URLs) and formats (PNG, PDF, ZPL) and the precondition of purchased postage, offering useful behavioral context.

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

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

The description is a single concise sentence that front-loads the action and resource. Every word adds value, 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's simplicity (one parameter, no output schema), the description is complete: it states the purpose, the output formats, and the prerequisite. The readOnlyHint annotation covers the safety profile, so no additional elaboration 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 provides full coverage for the single parameter 'id' with the description 'Shipment ID'. The tool description does not add additional parameter-specific meaning, so it meets the baseline but does not exceed 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 gets label download URLs in PNG, PDF, and ZPL formats for a shipment with purchased postage. It uses a specific verb and resource, distinguishing it from sibling tools like chitchats_get_shipment or chitchats_get_rates.

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 'with purchased postage' implies this tool is used after postage has been purchased, providing contextual guidance. However, it does not explicitly name alternatives or state when not to use 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 readOnlyHint annotation already declares the tool safe for reads, and the description's 'Get' is consistent with that. However, the description adds no additional behavioral context beyond listing output fields—no mention of response format, edge cases, pagination, or prerequisites. Since annotations already cover the safety profile, the description provides minimal extra value here.

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

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

The description is a single, efficient sentence that front-loads the main action ('Get line items for a shipment') and packs relevant field details without waste. Every word 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?

No output schema exists, so the description is the sole source for understanding the return value. It lists key fields (HS codes, SKUs, weights, etc.), which is helpful, but it does not clarify whether the result is an array or a single object, nor does it mention not-found behavior. For a simple 1-parameter tool, this is still reasonably complete.

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

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

Schema description coverage is 100% for the 'id' parameter, so the description does not need to explain it further. The phrase 'for a shipment' does imply the ID refers to a shipment, but this is already clear from the schema. 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 action ('Get') and the resource ('line items for a shipment'), and lists specific data fields (HS tariff codes, SKUs, etc.). This distinguishes it from sibling tools like chitchats_get_shipment, which likely returns shipment-level details rather than line 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 explicit guidance is given on when to use this tool versus alternatives. The description implies it is for fetching line items, but does not name alternative tools or mention exclusions (e.g., 'use chitchats_get_shipment for shipment-level details').

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, which is supported by the verb 'Get'. The description adds that the response includes costs, delivery times, and carrier options, providing some output context. However, it omits potential behavioral details such as data freshness, pagination, or performance considerations.

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

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

The description is one concise sentence that front-loads the verb and resource, listing what the tool returns without any unnecessary verbiage.

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 covers the essential output aspects (costs, delivery times, carrier options). It is adequate but could be slightly more complete by noting any prerequisites or links to related tools.

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

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

The input schema already fully describes the single parameter 'id' as 'Shipment ID', achieving 100% schema description coverage. The description's mention of 'for a shipment' aligns with this but adds no additional semantic detail beyond the schema.

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

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

The description clearly states the action 'Get' and the resource 'all available shipping rates for a shipment', including costs, delivery times, and carrier options. It is specific enough to distinguish from general shipment operations, though it does not explicitly differentiate from the similar sibling tool refresh_rates.

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 refresh_rates or get_shipment. The description does not mention any when-to-use or when-not-to-use scenarios, leaving the agent without context for tool selection.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds useful context by naming the exact categories of returned data (cost breakdown, tracking info, recipient details). For a simple retrieval tool, this is sufficient behavioral disclosure; no contradictions exist.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, then lists valuable details. Every word earns its place with no filler or redundancy.

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

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

For a one-parameter read-only retrieval tool with no output schema, the description is complete: it names the identifying input, clarifies the scope ('a specific shipment'), and previews the return content. The readOnlyHint covers safety expectations, and no further output explanation is required.

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 provides 100% coverage for the single parameter ('id': 'Shipment ID'). The description reinforces the role of the ID by saying 'specific shipment by ID' but does not add meaningful new semantic detail 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 uses a specific verb+resource structure: 'Get full details of a specific shipment by ID' and enumerates the included content (cost breakdown, tracking info, recipient details). This clearly distinguishes it from sibling tools like chitchats_list_shipments (list all) and chitchats_track_shipment (tracking-only).

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 clearly implies when to use this tool: when you have a specific shipment ID and need full shipment details. It does not explicitly mention alternatives or exclusions, but the 'specific... by ID' phrasing provides clear context relative to sibling list/track tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds mention of optional filters and pagination, but these are already in the schema. No additional behavioral details (e.g., return format, edge cases) are provided, but with annotations, this is acceptable.

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

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

A single sentence that front-loads the core action ('List batches') and packs in the key modifiers. No wasted words or redundancy.

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

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

For a simple list operation with three optional parameters and no output schema, the description is sufficiently complete. It conveys the essential purpose and mentions both optional filtering and pagination, which are the main functional attributes.

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

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

Schema coverage is 100%, so all parameters are already documented. The description repeats the existence of status filter and pagination but does not add any additional semantics beyond what the schema provides. This meets the baseline 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 the tool lists batches, a specific verb+resource combination. It also notes optional status filtering and pagination, which differentiates it from sibling tools like get_batch (single batch) or count_batches.

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

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

The description implies use for listing batches with optional status filters and pagination, providing clear context. It does not explicitly mention when not to use alternatives such as get_batch, but the 'list' vs 'get' distinction is clear enough for most agents.

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 no behavioral context beyond what the readOnlyHint annotation already provides. It does not disclose any specific behaviors such as filtering defaults, return format, pagination behavior, or whether all returns are listed across accounts. The description is essentially a restatement of the tool name with the word 'optional filters', which is already inferable from the schema.

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

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

The description is a single, concise sentence that is front-loaded with the core action and resource. It contains no unnecessary words or details, making it easy to parse quickly. 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?

The tool is simple with no output schema, but the description combined with the schema and readOnlyHint provides a minimally viable understanding. Missing are any details about what the response contains (e.g., list of return objects with fields) or any nuances like default pagination. However, for a straightforward list operation, this may be sufficient, though a more complete description could mention common usage patterns.

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

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

Schema description coverage is 100%, and all four parameters (page, limit, reason, status) have clear descriptions in the schema. The description's mention of 'optional filters' adds no semantic value. Baseline 3 is appropriate because the schema does the heavy lifting, and the description does not enhance parameter understanding.

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 'List return shipments', using a specific verb ('list') and resource ('return shipments'), which directly distinguishes it from sibling tools like chitchats_list_shipments. Even without the name, the description alone makes the tool's purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The sibling chitchats_list_shipments exists, and while 'return shipments' implies a distinction, there is no explicit statement like 'Use this to list returns, not shipments' or mention of when not to use it. The usage context is only implied by the tool name, not the description.

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

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds 'Supports pagination' and lists filter dimensions, but these are largely reflected in the schema. It doesn't disclose additional behavioral details like rate limits or default response structure beyond the schema.

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

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

The description is three short sentences, front-loaded with the main action, and contains no fluff. Each sentence earns its place: purpose, usage, and pagination.

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 provides essential context for a read-only list/search tool with 7 parameters and no output schema. It mentions pagination and common filters, which is sufficient for basic usage. It doesn't describe the response format, but the tool name and read-only nature imply a list of shipments, and the schema explains parameters.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description reiterates filter categories (order ID, status, date range, batch) but doesn't add new meaning beyond the schema. Baseline 3 applies.

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

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

The description starts with a specific verb+resource: 'List and search shipments with filters.' It clearly distinguishes from siblings like get_shipment (single) and count_shipments (count) by indicating a listing/searching operation.

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

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

The description explicitly says 'Use this to find shipments by order ID, status, date range, or batch,' providing clear when-to-use context. It doesn't mention when not to use it or name alternative tools, but the use case is clear enough.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the update action but does not mention side effects, permanence, return values, or any required permissions, leaving significant gaps for a mutation tool.

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

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

The description is exactly two sentences, front-loaded with the action and followed by a concise use case. Every word earns its place 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?

Given the tool's relative simplicity and full schema coverage, the description is nearly complete. It covers the purpose and use case, but with no output schema and no annotations, a brief mention of what the tool returns would improve 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 description coverage is 100%, so the schema fully documents all parameters. The description does not add extra meaning beyond mentioning 'dimensions' and 'package size', which is already covered by the parameter names and descriptions.

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

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

The description clearly states the tool updates shipment dimensions and refreshes rate quotes, using a specific verb and resource. It implies a unique scope compared to siblings like chitchats_get_rates, but does not explicitly differentiate itself.

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

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

The phrase 'Useful when package size changes' provides clear context for when to use this tool. It does not explicitly mention exclusions or alternatives, but the use case is well implied.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It states the high-level action but does not disclose side effects, such as whether the refund is automatic, whether the postage is invalidated, or whether the operation is reversible. For a financial/refund action, this is a significant gap.

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

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

The description is a single, clear sentence with no filler or redundant information. It front-loads the action and the target resource, making it easy to parse quickly.

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 (one parameter, no output schema), but the absence of annotations means the description should provide more context about expected behavior and side effects. It is minimally viable for selecting and invoking the tool, but lacks crucial refund-related context like whether a refund request is guaranteed or if any postage is voided.

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 with a single 'id' parameter described as 'Shipment ID'. The description adds no additional meaning about the parameter beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('request a refund') with a clear resource ('a shipment with purchased postage'), making the action unambiguous. It distinguishes itself from sibling tools like buy_postage or delete_shipment by focusing on the refund operation.

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

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

The phrase 'with purchased postage' implies the tool should be used only for shipments that have already had postage purchased, which is a mild usage condition. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.

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?

No annotations are provided, so the description must carry full behavioral disclosure. It states the basic action but omits side effects such as whether removal is permanent, how it affects batch counts/status, or idempotency. This is a significant gap for a mutation-like operation.

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

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

The description is a single, concise sentence that is front-loaded with the action. Every word earns its place; no filler or 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?

The tool is simple with only one parameter and no output schema, so the description is minimally adequate. However, it lacks behavioral details like error conditions or side effects on batch state, leaving some contextual 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% for the single parameter (shipment_ids), and the schema already clearly documents its purpose. The description adds no extra nuance 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 uses a specific verb 'Remove' and clearly identifies the resource ('shipments from their current batches'). It directly distinguishes itself from sibling tools like add_to_batch, making its purpose unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, but the sibling context (notably chitchats_add_to_batch) implies this is the inverse operation. Usage context is implied rather than spelled out.

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; the description adds the 'public' qualifier, suggesting it is an unauthenticated lookup, and clarifies the response includes status and event history. No contradictions or missing critical behavioral caveats.

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

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

A single compact sentence with all key information front-loaded. No wasted words or redundancy.

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

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

For a simple single-parameter read-only lookup, the description provides the main return content (status, event history) and the public nature. It could optionally mention error behavior, but the low complexity makes this 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 coverage is 100% with the single parameter 'id' described as 'Shipment ID'. The description adds no additional parameter meaning beyond the schema, so baseline 3 applies.

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

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

Clear verb 'Get' plus specific resource 'public tracking information' for a shipment; explicitly mentions status and event history, which distinguishes it from siblings like chitchats_get_shipment or chitchats_list_shipments.

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 over related siblings such as chitchats_get_shipment or chitchats_list_shipments. The 'public' wording hints at a use case, but no explicit context, prerequisites, or exclusions are provided.

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