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

Annotations indicate non-read-only and non-idempotent, but the description adds crucial context: the side effect of ordering the delivery, the offer expiration window, and a detailed breakdown of 409 errors (inappropriate_status, old_version, offer_expired, state_mismatch) with corrective actions. This far exceeds the annotation hints.

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

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

The description is exactly three sentences, each serving a distinct purpose: describing the action and consequence, warning about expiration, and detailing error handling and version source. There is no redundancy or filler, and the most important information is front-loaded.

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

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

Despite having no output schema, the description is remarkably complete for a mutation tool. It covers the prerequisite status, the side effect of ordering, the time constraint, the source of the version parameter, and all relevant error scenarios with recommended recovery actions. This is more than sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions for both claim_id and version. The description adds valuable context beyond the schema by stating that version comes from get_claim, and the 409 error explanation for old_version clarifies the parameter's significance. This supplements the schema rather than repeating 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 confirms a claim after successful estimation and starts the courier search, with the consequence that the delivery is actually ordered. This uses specific verbs and resources, and the status precondition (ready_for_approval) distinguishes it from sibling tools like get_claim or cancel_claim.

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 states when to use the tool (after successful estimation, when status is ready_for_approval) and warns about the 10-minute offer expiration, implying prompt action. It does not explicitly name alternative tools, but the precondition is clear enough for an agent to select correctly.

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

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

The description discloses that cancelling an accepted claim is possible, that a paid cancellation incurs a fee, and lists specific 409 error conditions (old_version, inappropriate_status, free_cancel_is_unavailable). This adds behavioral context beyond the readOnlyHint/destructiveHint annotations, which already signal mutation and destructiveness. No contradiction exists.

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

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

The description is compact and front-loaded with the core action. It packs essential instructions and error information into a few sentences without extraneous content, making 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?

Given the tool's complexity (state-dependent cancellation, fees, versioning), the description covers all necessary context: prerequisites, parameter sources, fee implications, and likely errors. There is no output schema, but the description sufficiently informs the agent about expected behavior and failure modes.

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?

Though the schema already covers all parameters, the description enriches semantics by telling where each parameter comes from: cancel_state from get_cancel_info, version from get_claim, and claim_id from create_claim/search_claims. It also explains the free vs. paid meaning, adding clarity beyond the schema's enum 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's function: 'Cancels a claim (including an already accepted one).' This uses a specific verb and resource, and explicitly notes that even accepted claims can be cancelled, which distinguishes it from sibling tools like accept_claim or get_cancel_info.

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 usage guidance: it tells the caller to first get terms with get_cancel_info and pass its cancel_state, and that version comes from get_claim. This effectively defines a workflow and prerequisites, which is exactly what an agent needs to use the tool correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context by emphasizing that the returned price is a decimal STRING, not a number, and by listing typical error codes and meanings, which helps the agent interpret responses.

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 four sentences, focuses first on purpose, then output, then input, then errors. Every sentence adds value with no filler.

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

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

Even without an output schema, the description enumerates the return fields (price as string, currency_rules, distance_meters, eta, zone_id) and lists common error scenarios. For a read-only estimation tool, this covers the key contextual needs for invocation and response interpretation.

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

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

Schema description coverage is 100%, so every parameter property already has a semantic description. The description adds minimal extra parameter detail (e.g., reinforcing that route points can use coordinates and/or address), but the schema already provides that, so a 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 'Preliminary delivery cost estimate WITHOUT creating a claim' and 'the pricing method for countries outside Russia', which differentiates it from claim-management siblings. The verb 'estimate' plus resource 'delivery cost' makes the purpose specific and 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?

It provides clear context: use for preliminary cost estimates before creating a claim, and only for countries outside Russia. However, it does not explicitly name an alternative tool for Russia or when to use a different tool, so it lacks a full when-not/alternatives statement.

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

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

The description discloses significant behavioral traits: non-immediate dispatch, status transitions, potential error_messages in a 200 response, and request_id-based idempotency. These go well beyond the sparse annotations (readOnlyHint=false, etc.), giving the agent critical expectations about side effects and error handling.

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

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

The description is dense and front-loaded, but at ~4 sentences, it is longer than the 'two sentences' ideal. Every sentence conveys necessary information—workflow, return values, verification, idempotency—so it is not verbose, but it could be tightened.

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 16 params, nested objects, no output schema, and complex state transitions, the description covers all essential operational aspects: what it creates, the estimation flow, required confirmation, return payload fields, verification method, error behavior, and idempotency. This is sufficient for an 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?

The schema provides 100% description coverage for all 16 parameters, including nested objects. The description adds context for request_id (idempotency guarantee) and auto_accept (skips accept_claim), but these are already partially covered in the schema. Overall, the schema does the heavy lifting, so 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 opens with 'Creates a delivery claim', a specific verb+resource. It clearly distinguishes from sibling tools (get_claim, accept_claim, cancel_claim) by indicating it is the creation step. The additional detail about estimation workflow reinforces its unique role.

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 workflow context: claims go through estimation and need accept_claim or auto_accept, and verification via get_claim. However, it does not explicitly state when not to use this tool or mention alternatives like check_price for pricing-only queries, so it falls short of full guideline coverage.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description wisely adds domain semantics instead of restating safety. It explains the three cancel_state outcomes and the fee-related fields, which is valuable 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 two sentences, front-loaded with the purpose and sequencing instruction, followed by a compact but complete summary of return states. Every sentence earns its place with zero filler.

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

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

For a single-parameter, read-only lookup with no output schema, the description fully covers the return semantics and the cancellation precondition. It provides enough information for an agent to invoke and interpret 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?

The sole parameter claim_id is fully described in the schema with source and format details, so the description does not need to repeat it. The tool description adds no extra parameter-level meaning, but schema coverage is 100%, warranting the baseline score.

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

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

The description clearly identifies the tool as providing cancellation terms for a claim and explicitly relates it to cancel_claim, distinguishing its role. Although it lacks a direct verb like 'retrieve', the return-state explanation makes 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 explicitly states to call BEFORE cancel_claim, establishing a clear usage context. It does not enumerate alternative tools, but the pre-cancellation position is sufficient guidance for when to use it.

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

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

The description adds significant behavioral context beyond the annotations: it warns that estimation errors can appear as an error_messages array inside a successful 200 response, and enumerates known statuses for interpreting results. This is valuable, non-obvious information that goes well beyond the readOnly/idempotent hints.

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

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

The description is long but information-dense; every section (field list, status list, caution) serves a purpose. It is well-organized and front-loaded with the purpose, though the status enumeration could be trimmed if considered overlong.

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

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

With no output schema, the description fully compensates by listing all returned fields, known statuses, and the error_messages edge case. It provides a comprehensive picture of what the tool returns and how to interpret it, making it complete for a read-only info retrieval 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% for the single parameter (claim_id), which already explains its origin and format. The tool description adds no additional parameter semantics, so baseline 3 applies.

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

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

The description clearly states it returns 'Full claim information' and lists the specific fields (status, version, items, route_points, etc.), establishing a clear purpose of retrieving comprehensive details for a single claim. It does not explicitly differentiate from sibling tools, but 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 when full claim information is needed and notes that version is needed for accept/cancel, giving a weak contextual hint. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of clear usage guidelines.

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

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

Annotations already declare the tool as read-only, open-world, and idempotent. The description adds useful behavioral context by specifying the return values (code and attempts) and the 404 error condition, including a case where API issuance is prohibited. This goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and wastes no words. It efficiently conveys behavior, return values, and error cases.

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 tool, the description covers the return values and the main 404 error condition. While it does not elaborate on the format of the code or the meaning of 'attempts,' the information is sufficient for basic usage given the lack of output schema.

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

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

The schema fully describes the single claim_id parameter with coverage at 100%, including instructions to use the ID from create_claim or search_claims responses. The description adds no additional parameter semantics, so it appropriately relies on 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 'get_confirmation_code' retrieves a pickup/delivery confirmation code for the current point of a claim, with a scope qualifier ('when a code applies'). This is specific and distinct from sibling tools like get_claim or get_courier_phone.

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 context ('when a code applies') but does not explicitly state when to choose this tool over alternatives or when not to use it. It lacks exclusionary guidance or references to sibling tools, so usage is inferred rather than 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 and idempotentHint=true. The description adds valuable context: the number is temporary, has a TTL, and includes specific error codes (400, 404, 409). This goes beyond the annotations without contradicting them.

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, well-structured sentence listing output fields and error codes. It is front-loaded and every word adds value, with no fluff or repetition.

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

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

Given no output schema, the description explains the return values and errors sufficiently. It could mention what constitutes an 'active claim' more explicitly, but the error information compensates. The context is otherwise complete for a simple read tool.

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

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

Schema description coverage is 100% (both claim_id and point_id have descriptions). The tool description adds no extra parameter-level detail, relying entirely on the schema. 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's function: providing a temporary forwarded phone number to call the courier of an active claim. It specifies the returned fields (phone, ext, ttl_seconds), distinguishing it from siblings like get_confirmation_code or get_tracking_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 notes the tool is for active claims and lists a 409 inappropriate_status error for completed orders, implying when not to use it. It doesn't explicitly name alternatives, but the context is clear and the sibling list provides 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the exact response structure and error conditions (404, 409). This adds behavioral context about expected failures and what data will be returned, which is valuable for an agent deciding whether to call this tool.

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

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

The description is a single, information-dense sentence followed by a compact error list. It front-loads the main purpose and output, with no wasted words or redundant repetition of schema data.

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

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

With a single parameter, no output schema, and annotation coverage, the description provides enough context: response fields, route_points, sharing_link, and specific error semantics. It could mention pagination or rate limits, but these are likely not relevant for a single-position endpoint. Overall, it is complete for the tool's 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 coverage is 100% with a detailed description of claim_id (32–64 chars, from create_claim or search_claims). The tool description adds the critical semantic constraint that the claim must be active, which is not in the schema, enhancing 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 the tool returns the current courier geoposition for an active claim, listing the specific fields (lat, lon, timestamp, accuracy, speed, direction) and route_points with sharing_link. This directly aligns with the tool name and distinguishes it from siblings that provide different tracking or courier info.

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 active claims by noting error 409 when the claim is not active or no courier is assigned. However, it does not explicitly compare with alternative tools like get_courier_phone or get_tracking_links, nor state when-not-to-use. The context is clear but no exclusions or 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?

Beyond the readOnly and idempotent annotations, the description discloses specific error conditions (404 not_found, 409 when claim inactive/no courier/unknown position) and the exact structure of the response. This adds substantial behavioral context 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 three sentences: purpose, precondition, and return/error details. Every sentence provides essential information, and the structure is front-loaded with the core purpose.

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

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

With no output schema, the description fully enumerates the returned object fields and error cases. For a single-parameter read operation, this covers all necessary context for an agent to invoke and interpret results 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?

The schema already describes claim_id with context (source from create_claim or search_claims responses). The description adds no additional parameter details beyond that, so a baseline of 3 is appropriate given 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 what the tool returns: expected arrival times per route point plus the current courier position. It specifies the resource (route points for a claim) and distinguishes it from sibling tools like get_performer_position by including ETAs and visit statuses.

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 for when the tool works: only while the claim is active and a courier is assigned. It does not explicitly name alternatives or exclusions, but the precondition and return content make appropriate usage 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?

The description adds behavioral context beyond annotations by disclosing the return format, the condition that sharing_link only appears for type=destination points, and possible 409 error codes. It does not contradict the readOnlyHint/idempotentHint annotations, and the disclosed behaviors are relevant for handling responses and errors.

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

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

The description is concise (two sentences), front-loaded with the key purpose, and effectively includes essential details: safe-to-share, return structure, conditional field, and error codes. Every piece of information 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?

For a simple tool with one parameter and no output schema, the description is fairly complete. It covers the return shape, the conditional availability of sharing_link, and error codes. It could be more complete by explicitly stating when to use it, but overall it provides sufficient context for an agent to invoke and interpret results.

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

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

The schema covers the only parameter (claim_id) with a clear description (source and length). The tool description adds no additional parameter detail, but since schema coverage is 100%, 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 tool's purpose: obtaining public courier tracking links safe to share, and it specifies the return structure (route_points with sharing_link). However, it does not explicitly differentiate itself from sibling tools like get_claim or get_confirmation_code, though the 'public tracking links' and return format make the purpose clear.

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

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

The description implies usage context by stating the links are 'safe to share with the recipient', suggesting this tool is for sharing tracking info with customers. However, it lacks explicit guidance on when to use this tool instead of alternatives, such as get_claim, which might also contain tracking information.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description adds crucial details: state-changing operations possible, retry only for GETs on 5xx/network errors, and specifics about how query and body are mapped. This enriches the agent's understanding without 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?

The description is two well-structured sentences plus a focused caution. It is front-loaded with the core purpose, follows with usage details, and ends with safety warning. Every sentence contributes necessary information without redundancy.

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

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

Given the tool's open-ended nature and lack of output schema, the description covers purpose, usage boundaries, parameter behavior, and risk—sufficient for an agent to select and invoke it correctly. It is remarkably complete for an escape-hatch 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?

While the schema already describes each parameter (100% coverage), the description adds meaningful context: paths are relative to the API root, query becomes query string, body is sent as JSON, and method defaults to POST. This goes beyond the schema descriptions and clarifies the HTTP mapping.

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

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

The description clearly identifies the tool as an escape hatch for direct calls to the Yango Delivery API, explicitly listing example endpoints and specifying it is for endpoints without a dedicated tool. This strongly differentiates it from sibling tools like get_claim or cancel_claim.

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

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

Provides explicit when-to-use guidance by stating 'for endpoints without a dedicated tool' and giving concrete examples. It also cautions about state-changing operations and retry behavior, which helps agents decide when to use it versus safer dedicated 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 mark it as read-only and idempotent, so the description adds value by disclosing the return shape (claims like get_claim, plus a cursor), the sort order (creation date), and the pagination semantics (either offset/limit or cursor from previous response). This is beyond annotation data.

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

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

Three concise, information-dense sentences. Front-loaded with the main purpose, then return shape, then pagination alternatives. No redundant 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 complex tool with 12 optional parameters and no output schema, the description adequately covers the core behavior: searching with filters, sorted results, return shape (same as get_claim), and cursor pagination. The schema handles parameter details, so no need to list every filter.

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 each parameter has a description. The main description adds little beyond the schema, only reiterating the cursor-based pagination mode already covered in the cursor parameter description. Baseline for high coverage 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 uses a specific verb 'Search' and resource 'claims', clearly distinguishing it from sibling tools like get_claim (singular retrieval). It also specifies 'by filters with pagination' and 'sorted by creation date', which defines the tool's 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?

It provides clear context on when to use this tool: to search claims with filters. It also explains two pagination modes (offset/limit or cursor-based) and notes that cursor-based pagination doesn't require other filters. However, it doesn't explicitly mention alternatives like get_claim for single claim retrieval, so no strong exclusion is given.

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