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

The description adds value beyond the annotations by stating the return shape ({success, id}) and the optional order attribution behavior. Annotations already indicate this is a write operation that is not destructive, and the description is consistent. It does not disclose potential pitfalls like multi-site key requirements, but those are in 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, focused sentence followed by a return-value note. It is concise, front-loaded, and contains 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?

For a simple create operation with complete schema documentation and an explicit return format, the description covers the essential context. It could mention requirements like site for multi-site scopes, but that is already in the schema. Overall, it is sufficiently complete.

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

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

The schema provides 100% coverage with descriptions for all 7 parameters, so the description is not required to explain parameters. It does mention optional attribution to an order, which maps to order_id, but this is already in the schema. No additional parameter semantics are added.

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 ('Create') and resource ('expense record'), and clarifies optional order attribution. This clearly distinguishes it from sibling creation tools like create_order or create_customer.

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 recording an expense but provides no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The presence of list_costs suggests a complementary role, but it is not stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description does not need to cover safety. It adds the return value ({success, id}) and highlights 'optional externalId', which provides some behavioral context beyond annotations. However, it does not discuss permissions, idempotency, or other operational nuances.

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 clearly states the action and resource, lists major inputs, and includes the return value. Every word earns its place; there is no redundancy or fluff.

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

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

Given 10 parameters and no output schema, the description provides a solid high-level overview and the return shape. It does not repeat schema details, which is fine. However, it doesn't mention edge cases like the conditional requirement for 'site' when the API key is scoped to multiple stores, but that is covered in the schema. Overall, sufficient 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 detailed descriptions for all 10 parameters. The tool description summarizes them as 'name, contacts, address, optional externalId' but does not add new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema fully documents parameters.

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

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

The description clearly states the action ('Create') and the resource ('a customer'), and lists key fields ('name, contacts, address, optional externalId') which distinguishes it from sibling tools like update_customer or list_customers. It also includes the return format ({success, id}), 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 implies usage for creating a new customer but does not explicitly state when to use this tool versus alternatives like update_customer or merge_customers. There is no mention of exclusions or prerequisites, so guidance is only implicit from the verb 'Create'.

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

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

The annotations only indicate readOnlyHint=false and destructiveHint=false, so the description must carry behavioral disclosure. It adds valuable context by disclosing that a customer may be created inline (side effect) and by specifying the return value shape {success, id, order?}. It does not contradict annotations.

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

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

The description is two sentences, each earning its place. The first gives the primary purpose, the second covers customer handling and the return format. No fluff or repetition of schema 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?

With 13 parameters but no output schema, the description provides key routing information (customer linking options) and the return structure. The schema sufficiently describes individual parameters, and the description fills the main decision gap without overwhelming the agent. It could mention delivery-related parameters but that is adequately covered in the schema.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds extra meaning by explaining the relationship between customer_id/customer_external_id and the inline name/phone/email parameters, clarifying mutual exclusivity and when to use each. This goes beyond individual parameter 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 creates an order with line items and delivery, using the specific verb 'create' and resource 'order'. It also distinguishes from sibling tools like update_order and list_orders by focusing on creation, and differentiates from create_customer by mentioning inline customer creation as part of order creation.

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 usage context by explaining the two ways to handle customers: linking an existing one via customer_id/customer_external_id or passing first_name and contact details to create one inline. While it doesn't explicitly state when not to use this tool versus alternatives, the guidance on customer linking gives practical usage direction beyond a simple imperative.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's 'Add a note' aligns with a write operation. It adds useful context by stating 'Returns {success, id}', disclosing the response shape, and by highlighting that either customer_id or customer_external_id can be used. However, it does not discuss side effects, idempotency, or authorization requirements, which would deepen transparency.

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, front-loaded with the action ('Add a note') and provides the return value in a compact parenthetical. Every word contributes value, with no repetition of schema field descriptions or annotation 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 straightforward create tool, the description covers the essential aspects: purpose, target resource, identification options, and return value. It omits the site requirement for multi-site API keys, but that is already documented in the schema, so the description does not need to repeat it. Error conditions or prerequisites are not mentioned, but the absence is acceptable given the tool's simplicity and the supportive schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small but meaningful clarification that the customer can be identified 'by id or externalId', linking customer_id and customer_external_id. It also implicitly prioritizes text as the note content, but does not add syntax or formatting details beyond the schema.

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

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

The description uses a specific verb ('Add') and resource ('note to a customer'), clearly distinguishing it from sibling tools like customer_notes_list and customer_notes_delete. It also specifies both identifying methods (id or externalId), which disambiguates it from other customer-related create operations.

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

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

The description states that it adds a note to a customer, implying it is the correct tool for creating customer notes. However, it does not explicitly contrast with alternatives (e.g., 'For listing notes, use customer_notes_list' or 'For removing notes, use customer_notes_delete'), nor does it mention conditions like the site requirement for multi-site API keys. Usage context is implied but not fully elaborated.

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

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

Annotations already declare destructiveHint=true, so the description is not required to reiterate destructiveness. It adds the return format ({success}), which is useful, but does not describe other behavioral traits such as irreversibility or effect on related data. Given the annotations, the description provides minimal added context.

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

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

The description is a single, succinct sentence that communicates the action and return value with zero unnecessary words. It is front-loaded and perfectly sized for the tool's simplicity.

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 that this is a simple single-parameter delete with no output schema and strong annotations (destructiveHint=true), the description is nearly complete. It could optionally mention irreversibility, but the annotation already covers this. The return format is provided, so no critical information is missing.

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

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

The schema description for the 'id' parameter already states 'Note ID to delete', and the description repeats 'by id'. Since schema description coverage is 100%, the description adds no 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 uses the specific verb 'Delete' with the resource 'customer note' and the qualifier 'by id'. This clearly distinguishes it from sibling tools like customer_notes_list and customer_notes_create, 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 clearly implies when to use this tool (when you need to delete a customer note by its ID). It does not mention alternatives or exclusions, but the context is clear from the verb and resource. For a simple delete operation, this level of guidance is sufficient.

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 agent knows this is a safe read. The description adds the return structure ({notes[], pagination}) but does not disclose additional behavioral traits such as pagination defaults or filtering nuances beyond what the schema provides. 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 states the action and the return shape. There is no fluff or redundant information, making it highly efficient and well-structured.

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

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

For a simple list tool with no output schema, the description adequately covers the return format and the schema documents all parameters. It does not explain default pagination behavior explicitly, but defaults are present in the schema, so the description is complete enough for this simplicity level.

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 all four parameters clearly documented in the schema. The tool description does not add any additional parameter semantics 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 clearly states the tool lists free-text notes attached to customers, with a specific verb and resource. It is immediately distinguishable from sibling tools like customer_notes_create and customer_notes_delete, 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 for when to use this tool—when needing to retrieve customer notes—and there are no alternative listing tools among siblings. It lacks explicit exclusions or references to alternatives, but the purpose is self-evident.

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 establishes the safe read-only nature, and the description adds the return structure '{history[], pagination}' which is useful. However, it doesn't disclose details like ordering, default behavior, or any constraints beyond what the schema already covers. The description adds some context but not rich behavioral insight.

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: two sentences, first defining purpose, second defining return shape. Every word earns its place with no 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 read-only log tool with 6 optional parameters fully described in the schema, the description gives the purpose and return shape, which is sufficient. It doesn't explain the field-change entry structure, but that's implied and not critical for selection. Sibling differentiation is clear, and annotations handle safety.

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 parameters are fully documented. The description itself doesn't elaborate on parameters, but the baseline of 3 is appropriate since the schema handles the semantic load. No additional value is provided 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 identifies the tool as a 'Customer field-change log', which is a specific resource distinct from sibling tools like orders_history. It also states the intended use for 'growth/churn signals and incremental sync', making the purpose unmistakable despite lacking an explicit verb like 'get' or 'list'.

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 growth/churn analysis and incremental sync, which provides context for when to use this tool. It doesn't explicitly exclude alternatives, but the purpose is clear enough to differentiate from list_customers or get_customer. A more explicit comparison to orders_history would earn a 5.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds the return format ('Returns {file}'), which is useful but does not disclose additional behaviors like error handling or auth requirements. With annotations covering safety, 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?

Two sentences, zero wasted words. The description is front-loaded with action and resource, and the return value is stated succinctly.

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

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

For a simple one-parameter read tool with no output schema, the description is complete: it states the action, the parameter, and the return shape. No additional context is necessary.

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

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

Schema description coverage is 100%, with the 'id' parameter documented as 'File ID to fetch metadata for'. The description's 'by id' adds nothing beyond the schema, so it meets the baseline without enhancing semantics.

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

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

The description clearly states the action ('Get') and the resource ('file's metadata'), with the scope 'by id'. It differentiates from sibling tools like files_list and files_upload by specifying metadata retrieval for a single file, 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 phrase 'by id' clearly indicates the tool is used when you have a file ID and need metadata, providing clear context for use. No explicit exclusions or alternative tool mentions, but the usage context is evident from 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?

The description adds the return format `{files[], pagination}`, which is helpful beyond the readOnlyHint annotation. However, it does not disclose behaviors like default filtering scope or that all files are returned if no filters are applied. The annotation already covers read-only safety, so the bar is met minimally.

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

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

Two sentences that are front-loaded with the action and resource. No redundant information. 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 read-only list tool with 5 optional parameters and no output schema, the description provides the essential return shape and scope. It lacks explicit guidance on default behavior or alternatives, but it is sufficiently complete for a basic list 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?

The schema provides 100% coverage for all 5 parameters with descriptions. The tool description adds no extra syntax or format details beyond what the schema already contains. The mention of 'orders/customers' aligns with filter params but adds no new meaning.

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

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

The description clearly states the verb 'List' and resource 'files' with specific scope 'attached to orders/customers'. This distinguishes it from sibling list tools like list_orders and list_customers. The return shape is also noted.

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

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

The intended use case (listing files) is clear from the description. However, it does not explicitly mention when not to use it or suggest alternatives like files_get for individual file retrieval. The context is unambiguous but lacks explicit exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this performs a write operation. The description adds the return format {success, file}, which is helpful given there is no output schema, and mentions supported content encodings.

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, front-loaded with the action, followed by the return format. Every word adds value, with no repetition of schema details or annotations.

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

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

For a simple upload tool, the description combined with the fully documented schema covers the purpose, parameter usage, and return value. It omits edge-case behavior like overwriting existing files, but this is not critical for basic usage and the destructiveHint=false annotation implies no destructive overwrite.

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

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

The input schema provides 100% coverage with descriptions for all four parameters, including the base64 flag and content_type. The description does not add new parameter semantics beyond what the schema already explains, 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 uses the specific verb 'Upload' with the resource 'file', and clarifies accepted content formats (UTF-8 text or base64 binary). This clearly distinguishes it from sibling tools like files_list and files_get, which perform read operations.

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 to use the tool: to upload a file. No alternatives to uploading exist among siblings, so explicit exclusions are unnecessary, making this clear enough for an agent to select 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 behavioral context beyond the readOnlyHint annotation by explaining that it returns a 'shaped customer' and that detail:'full' includes address and contact details. It doesn't mention raw mode or error behavior, but the readOnly annotation covers safety, and the schema details raw. This is good for a simple read 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 two concise sentences, front-loaded with the main purpose and then providing a key behavioral detail. Every word earns its place, with no unnecessary fluff or repetition of schema 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 single-customer retrieval tool, the description combined with the rich schema (100% coverage) and readOnlyHint annotation provides complete context. It covers the purpose, the lookup methods, and the output verbosity, which is all an agent needs to select and invoke this tool effectively.

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 has 100% coverage with detailed descriptions for all 4 parameters. The description adds meaning by explaining the lookup via 'id or externalId' and clarifying what detail:'full' provides (address and contact details). This enriches the schema without redundancy, so a score above baseline is warranted.

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 a single customer by id or externalId', specifying both the action and the resource. It distinguishes itself from sibling tools like list_customers by focusing on a single customer lookup. The mention of 'shaped customer' and detail levels adds further clarity.

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 context is clear: use this when you need a single customer record identified by id or externalId. It doesn't explicitly compare with alternatives like list_customers, but the phrase 'single customer' implies the distinction. No exclusions are mentioned, but the purpose is unambiguous 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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the return shape {period, newCustomers} but does not elaborate on aggregation granularity or edge cases. This is acceptable but not rich—hence a 3.

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 the return signature, tightly packed with no redundant words. It is front-loaded and efficient.

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

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

The tool is simple (two dates, a count), and the description covers the return shape. However, the meaning of 'period' is ambiguous—whether it equals the requested range or a breakdown. Without an output schema, slightly more detail would make it fully complete.

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

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

Schema covers both parameters fully (100% description coverage) with start/end dates and format patterns. The description only confirms 'for a date range,' which adds minimal value beyond the schema. 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 the tool's purpose: 'Period-scoped new-customer count for a date range.' This distinguishes it from sibling tools like list_customers (individual details) and get_orders_summary (orders). The return shape {period, newCustomers} further clarifies the function.

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

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

The description implies usage context ('for a date range') but does not explicitly state alternatives or when not to use this tool. It provides clear context without exclusions, which aligns with a 4.

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 read-only nature is covered. The description adds useful behavioral context about the 'shaped' output and the effect of detail:'full' (adding items, delivery, payments, comments). However, it does not disclose error behavior or the 'raw' debug option (though the schema covers it). Overall, it adds modest value beyond annotations.

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

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

The description is exactly two sentences, front-loaded with the primary purpose. Every sentence adds meaningful information, and there is no redundancy or unnecessary detail. It is concise and well-structured.

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

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

For a simple read-only tool with no output schema, the description covers the essential behavior: single order retrieval, lookup fields, and the summary/full detail modes. The annotations confirm read-only behavior, and the schema documents all parameters. Minor omissions like explicit error handling or mention of the raw flag are not critical given the schema, so it is nearly 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%, with all parameters (by, id, raw, detail) already well-documented. The description's mention of 'shaped order' and detail behavior aligns with but does not significantly extend the schema. The 'raw' parameter is absent from the description but is explained in 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 uses a specific verb 'Get' and resource 'single order', and clearly identifies the lookup fields (RetailCRM id or externalId). It distinguishes itself from sibling tools like list_orders by explicitly saying 'single order', 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 implies when to use this tool: when you need a single order by ID/externalId. It provides clear context but does not explicitly mention alternatives or exclusion conditions, such as 'use list_orders to retrieve multiple orders'. This is a minor gap, so it earns a 4.

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

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

The annotations provide readOnlyHint: true, and the description goes beyond this by disclosing that the summary may be partial (partial:true) if the max_pages window is exceeded, that totalCount is always exact, and that revenue/status are computed over a limited aggregation window. This adds meaningful behavioral context beyond the annotation.

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

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

The description is a single, dense sentence that front-loads the core purpose and packs in all key behavioral details (exact count, metrics, partial flag). No wasted words; every clause 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?

With no output schema, the description covers the main return values (totalCount, revenue, AOV, status distribution, partial flag) and the aggregation window. It does not mention filter_status default behavior or error cases, but for a read-only summary tool with good metric coverage, it is 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 has 100% coverage with property descriptions that already explain max_pages (window of 100 orders, count always exact) and date format. The description reinforces these semantics but does not add new parameter-level details beyond the schema, which takes the baseline score of 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 purpose with a specific verb ('summary') and resource ('orders'), and lists concrete outputs (totalCount, revenue, AOV, status distribution). It distinguishes itself from siblings like list_orders (which lists orders) and get_customers_summary (which summarizes customers) by focusing on period-scoped order aggregates.

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 usage is implied by the word 'summary' and the described metrics, but there is no explicit guidance on when to use this tool instead of list_orders or get_customers_summary. No 'when not to use' or alternative tool references are provided, though the purpose is clear enough for an agent to infer.

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

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

Annotations already provide readOnlyHint=true, and the description does not contradict this. Beyond the annotation, the description discloses the return shape '{costs[], pagination}', which gives the agent insight into the result structure and pagination behavior. This is useful contextual information not present in the annotation.

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

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

The description is a single sentence plus a return type snippet. It is front-loaded with the verb 'List', and every word adds value: the resource, the purpose, the filter dimensions, and the return shape. No fluff 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 5-parameter list tool with no output schema, the description provides the return shape ('{costs[], pagination}') and the purpose, which covers the essential context. It does not explain every parameter, but the schema handles that. It could mention default sorting or explicitly state read-only, but the annotation covers the latter, so it is sufficiently complete.

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

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

Schema description coverage is 100% (all 5 parameters have descriptions), so the baseline is 3. The description mentions filtering by 'date and cost group', but this simply mirrors the schema parameter descriptions without adding new meaning. It does not compensate with additional parameter-level context.

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

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

The description opens with a specific verb and resource: 'List expense records'. It also adds the purpose 'for margin/profit analytics' which distinguishes it from other list tools like list_orders or list_customers. This clearly identifies what the tool does.

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

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

The phrase 'for margin/profit analytics' gives a clear context for when this tool is appropriate, and the mention of 'by date and cost group' hints at filtering use cases. It does not explicitly exclude alternatives, but the sibling tools (e.g., create_cost, list_orders) are clearly different resources, making the usage intuitive.

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 readOnlyHint=true in annotations, the agent knows it is a safe read operation. The description adds no additional behavioral context such as output format, pagination, or caching behavior. It only provides a domain note ('valid ISO codes'), which is semantic rather than behavioral.

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 essential info (what it lists and its purpose). Every word earns its place, though it is terse. No redundancy or 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 simple list tool with one optional parameter and no output schema, the description states the subject matter ('country ISO codes') and its domain. However, it does not clarify the exact return structure (e.g., array of strings), which is left to the agent's inference from the name. It is minimally sufficient but lacks some detail.

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 includes a thorough description for the only parameter 'raw' (behavior and debugging purpose), achieving 100% coverage. The tool description does not add any information about parameters beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource as 'valid country ISO codes' and specifies its use case 'for addresses/delivery'. Although it lacks an explicit verb like 'list' or 'returns', the name 'list_countries' implies the action. It distinguishes from sibling list tools by focusing on country codes.

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

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

The phrase 'for addresses/delivery' provides implied usage context, suggesting when this tool would be relevant. However, it offers no explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or sibling comparisons are presented.

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 the description adds valuable behavioral context about the return format (pagination + array of specific fields) and the effect of detail:'full' (adds address/externalId/all phones). It does not contradict annotations and goes beyond the bare safety hint.

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: the first states purpose and filterable fields, the second specifies return structure and detail behavior. Every word earns its place with no fluff or repetition of schema 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?

Given the rich schema and readOnly annotation, the description sufficiently covers return values and the key detail parameter. It does not mention filter combination logic (AND/OR) or error behavior, but these are minor gaps for a listing tool. Overall, it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds meaning by explaining the summary output fields (ordersCount, totalSpent) and clarifying that detail:'full' expands the response with additional fields, which is not explicit in the schema.

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

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

The description uses a specific verb ('List/search') with a clear resource ('customers') and lists searchable fields (name, email, phone, created-date). It distinguishes from siblings like get_customer (single customer) and create_customer by clearly indicating a multi-result listing/search capability.

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 this tool is for listing/searching customers, but it does not explicitly state when to use it over alternatives (e.g., get_customer for a single record, create_customer for creation). No exclusions or alternative tool names are mentioned.

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

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

The readOnlyHint annotation already marks this as a safe read operation. The description adds the scope 'all' (implying no filtering) and mentions the output fields, but provides no additional behavioral context such as pagination, rate limits, or response format. It doesn't contradict annotations.

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

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

The description is a single, front-loaded sentence that conveys the essential information without any fluff. Every word earns its place, making it highly concise and well-structured.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description sufficiently explains what the response contains (codes, names, default costs). It lacks deeper details like sorting or status filters, but for a basic list tool with readOnlyHint, it is nearly complete.

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

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

The input schema covers 100% of parameters with a description for the 'raw' boolean property. The tool description does not reference the parameter, but the schema already provides adequate semantics, so the baseline of 3 applies.

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

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

The description 'All delivery types with codes, names, default costs' clearly identifies the tool as a list operation for delivery types and specifies the key fields returned. This distinguishes it from other list_* tools by naming the exact resource and scope.

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

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

The description implies when to use this tool (when delivery types are needed) but gives no explicit alternatives or exclusions. Sibling tools like list_payment_types or list_order_methods are not mentioned, so 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 readOnlyHint annotation already discloses the tool is safe to call, so the description does not need to repeat that. The description adds useful domain context by equating order methods with acquisition channels, but it does not mention return format, pagination, or any other behavioral traits. This is acceptable given the simplicity of the 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 extremely concise: a single phrase with no filler words. It is front-loaded with the key content 'All order methods' and immediately clarifies with the parenthetical 'acquisition channels'. Every word contributes value.

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

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

For a simple read-only list tool with one optional boolean parameter and no output schema, the description is almost complete. It clearly identifies what is returned. It could be slightly improved by explicitly stating that it returns a list of method labels, but the tool name and description together are sufficient.

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

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

Schema description coverage is 100% because the only parameter 'raw' is fully documented in the schema. The description adds no extra parameter information, but the baseline of 3 applies since the schema carries the full semantic load for parameters.

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

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

The description states the resource clearly: 'All order methods (acquisition channels).' It goes beyond the name by clarifying that order methods are acquisition channels, which distinguishes it from similar list_* tools. However, it lacks an explicit verb like 'Lists' or 'Returns', relying on the tool name to imply the 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 provides no guidance on when to use this tool versus alternatives. It does not mention related tools such as list_delivery_types or list_payment_types, nor does it state conditions or exclusions. Usage is only implied by the tool name and the noun phrase description.

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

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

Annotations already provide readOnlyHint:true, but the description adds valuable context: the return format (pagination + array of objects), the summary fields, and the behavior of detail and raw parameters. It does not discuss rate limits or auth requirements, but for a read-only list tool with annotated safety, this 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 two sentences, front-loaded with the primary action, and contains no filler. Every clause adds information: filter options, return summary, and parameter use cases. It earns its place.

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

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

Given 9 optional parameters and no output schema, the description provides a complete picture: it lists all filter dimensions, states the return shape (pagination + array with key fields), and explains how to access full details or raw payloads. It does not need to repeat schema defaults or parameter syntax, as those are already in the input schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful usage guidance for 'detail' and 'raw' parameters, explaining when to use them ('Use detail:'full' for line items/delivery/payments, raw:true for the untouched payload'). This goes beyond the schema's simple descriptions, though filters are only listed generically.

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: 'List orders with filters by status, customer name, number, and created-date range.' It uses a specific verb and resource, and the return shape is described. This distinguishes it from siblings like get_order (single order) and list_customers (different resource).

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 to use the tool: listing orders with various filters. It also explains when to use detail:'full' and raw:true, which are key parameter decisions. However, it does not explicitly mention alternatives like get_order for a single order, so it misses explicit exclusions or alternative tool guidance.

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

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

Annotations already declare readOnlyHint=true, lowering the transparency burden. The description adds useful context beyond the annotation by explaining the tool serves as an enumeration source for create_order, which is valuable behavioral information not present in the annotation.

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

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

The description is a single sentence that immediately conveys the tool's output and purpose. There is no wasted wording, and key information is front-loaded.

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

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

For a simple list tool with one optional parameter, the description is complete: it states the main content (order types with codes/names) and its purpose. No output schema exists, but the description implicitly covers the return shape enough for this use case.

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

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

Schema coverage is 100%: the single optional 'raw' parameter is fully documented in the schema with a description. The tool description adds no extra parameter details, but since the schema already covers everything, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists all order types (codes/names) and explicitly ties it to create_order's order_type, making its purpose specific and distinct from sibling list_* tools like list_statuses or list_payment_types.

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

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

The description indicates the primary use case: retrieving valid values for create_order's order_type. It does not explicitly name alternatives, but the context of 'valid values for create_order' provides clear when-to-use guidance.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds the specific piece of information that output includes codes and names, but it does not mention the 'raw' parameter's verbose behavior or any other potential side-effects. Given the annotation coverage, the description provides some additional context but is 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 short sentence that is immediately comprehensible. It contains no filler and gets straight to the point, making it ideal for quick parsing.

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

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

Given the simplicity of the tool (one optional read-only parameter, no output schema), the description plus schema provides sufficient context. It tells the agent what the tool returns, and the schema handles the only parameter. The absence of pagination or formatting details is not a significant gap for a presumably small list of payment types.

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

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

The input schema has one parameter, 'raw', with a complete description explaining its purpose. The tool description itself does not add parameter-related details, but schema coverage is 100%, 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 identifies the resource (payment types) and the expected output (codes and names). Though it lacks an explicit verb, the tool name 'list_payment_types' clarifies the action, making the purpose unambiguous. It distinguishes itself from sibling tools by naming a specific entity type.

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

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

There is no guidance on when to use this tool versus alternatives. No exclusions or alternative tool references are provided, leaving the agent to infer usage solely from the name and description.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds behavioral context by specifying the return shape ({productGroup[], pagination}) and the hierarchical nature (category tree), which are not covered by annotations or schema. It does not contradict annotations.

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

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

The description is a single, dense sentence that front-loads the core action and resource, then states the return format. Every word contributes value; there is 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?

For a simple read-only list tool, the description covers the essential context: what it lists, the hierarchical nature, and the response shape. Missing details like navigation semantics are minor and partially covered by the schema's filter_parent_group parameter. The tool is simple enough that this is adequate.

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

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

Schema description coverage is 100%, with each parameter already described (page, limit, filter_active, filter_parent_group). The description adds no additional parameter-level semantics, so the baseline of 3 applies.

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

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

The description clearly states the action ('List'), the resource ('product groups'), and adds unique context ('category tree') that distinguishes it from siblings like list_products or list_segments. It also explicitly mentions the return structure, leaving no ambiguity about the tool's purpose.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as list_products. It implies a hierarchical grouping use case via 'category tree', but does not state when to choose this over other list tools or how to navigate the tree.

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 readOnlyHint=true, so the safe read-only nature is already known. The description adds value by specifying the return shape ('Returns pagination + array of {id, name, article, active, url, groups, offers}') and the filter dimensions, providing behavioral context beyond the annotation without contradicting it.

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 sentence, front-loaded with the action and key resource, followed by filter types and return value. Every word is purposeful with no 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 8 optional parameters, rich schema, and readOnly annotation, the description is sufficiently complete: it covers the core purpose, filter types, and return structure. No output schema exists, but the description provides the key return fields, which is adequate.

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

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

Schema coverage is 100%: all 8 parameters have descriptions, so the baseline is 3. The description mentions filter names and price range, which aligns with schema parameters, but does not add additional semantic meaning beyond what the schema already states. It effectively reiterates the schema.

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

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

The description clearly states it 'List catalog products with filters by name, active, group, price range', which is a specific verb + resource + filter dimensions. It distinguishes from sibling tools like list_product_groups or list_orders by focusing on catalog products and their specific filter types.

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 to use the tool (when needing to list or filter catalog products), but does not explicitly mention when not to use it or point to alternatives. The filter_groups parameter does reference list_product_groups indirectly, but that is in the schema, not the description itself.

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 the description adds the return shape '{segments[], pagination}', which is useful behavioral context beyond the annotation. It also clarifies that segments are RFM/marketing cohorts, adding domain context. No contradictions with annotations.

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

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

The description is extremely concise: one sentence for purpose, one for return format. Every part 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 simple read-only list tool with fully described optional params, an annotation confirming read-only, and a stated return shape, the description is complete enough for an agent to use correctly. The absence of an output schema is mitigated by the return format hint.

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

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

The input schema provides complete descriptions for all four parameters, so the baseline is 3. The description does not add any additional parameter meaning, but it does not need to since the schema covers it fully.

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

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

The description clearly states the action ('List') and the resource ('customer segments'), and clarifies the domain with 'RFM/marketing cohorts'. This distinguishes it from other list tools like list_customers or list_products, making the purpose unmistakable.

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

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

The description implies the tool should be used to retrieve customer segments, but it does not explicitly mention when it should be used over alternatives or provide any exclusions. There are no obvious sibling alternatives for segments, so the context is somewhat clear, but guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true, and the description adds context about API-key scoping and the output code's purpose. However, it doesn't describe return format, pagination, or other behaviors, so the added value beyond annotations is modest.

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 states the purpose and key usage in a compact manner. No wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides enough context: it lists the resource scope and the purpose of the return value. Some ambiguity exists around 'sites/stores' vs the sibling `list_stores`, but overall it is complete for typical use.

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

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

Schema description coverage is 100% for the single optional `raw` parameter, which is well-documented in the schema. The description adds no additional parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states this tool lists all sites/stores the API key can act on, and specifies the returned code's use as a `site` parameter. It doesn't explicitly distinguish from the sibling `list_stores`, but the scope ('API key can act on') provides some differentiation.

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

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

The description gives explicit usage guidance: use the returned code as the `site` param on multi-site create/edit. It does not mention when not to use it or name alternatives, but the primary use case is clearly stated.

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

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

Annotations declare readOnlyHint=true, covering the safety profile. The description adds value by disclosing the content (codes, names, groups, ordering) and the intended usage context, but doesn't go beyond that (e.g., no pagination or inactive status details). With annotations lowering the bar, a score of 3 is appropriate.

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

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

Two crisp clauses, zero filler. One sentence, front-loaded with the resource and followed by a practical directive. 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?

Simple tool with one optional param and no output schema. The description covers what the tool returns (all order statuses with fields) and when to use it. No significant gaps for this 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?

The sole parameter 'raw' is fully described in the schema (100% coverage), so the description doesn't need to add parameter semantics. It doesn't, which is fine for the baseline.

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

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

The description clearly states the tool returns all order statuses with their codes, names, groups, and ordering, distinguishing it from other list_* siblings by specifying the resource and a concrete use case. The verb is implicit in the tool name, but the resource and content are explicit.

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

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

Provides explicit when-to-use guidance: 'Call before filtering/updating orders by status.' This tells the agent when to invoke this tool. However, it doesn't mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, which covers the safety profile. The description adds the behavioral nuance that it returns 'all' stores, implying no filtering, but does not disclose other traits like pagination or response structure. 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 short phrase with no filler. Every word contributes to identifying the resource and its key fields, making it highly concise and well-structured for a simple list tool.

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

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

For a tool with one optional parameter, no output schema, and a read-only annotation, the description is mostly complete. It names the returned fields (codes, names, types) and implies no filtering. It could mention the raw parameter behavior, but the schema already covers it, so the overall context 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 fully documents the single optional 'raw' parameter with 100% coverage, so the description does not need to add parameter meanings. The description offers no additional semantic context beyond the schema, which is acceptable given the 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 'All warehouses/stores (codes, names, types)' clearly identifies the resource and scope, distinguishing this list tool from siblings like list_orders or list_customers. However, it lacks an explicit verb ('list' or 'retrieve'), relying on the tool name to convey the action, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or context that would help an agent decide between list_stores and other list_* tools.

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

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

The description explicitly states that merged records are DELETED, which aligns with the destructiveHint=true annotation and adds behavioral specificity beyond the annotation. It also discloses the return shape as {success}, which is helpful given no output schema. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core action and key warning, and contains no redundant information. 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 merge operation, the description covers purpose, destructive behavior, and return type. The schema fully documents parameters. It could mention prerequisites or atomicity, but overall it is sufficiently complete for an agent to invoke 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 input schema already provides complete descriptions for both parameters (100% coverage), so the description adds minimal semantic value. The phrase 'merged records are DELETED' reinforces what happens to merged_customer_ids, but the schema already says 'will be deleted'.

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 ('Merge duplicate customers into a target') and highlights the key destructive consequence ('merged records are DELETED'). It is specific about the resource and operation, making it easy to distinguish from customer creation, update, or retrieval 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 context for when to use the tool: when there are duplicate customers to consolidate. It does not explicitly name alternative tools, but the purpose is evident given the sibling tool set (e.g., update_customer for single edits). This is clear context with no exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, establishing that this is a non-read-only, non-destructive write operation. The description adds the return shape {success, id}, which is valuable given no output schema, but it does not disclose additional behavioral traits like idempotency, permission requirements, or failure 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 optimally concise: two sentences, front-loaded with the action, and no redundant phrasing. The return value is included in the second sentence, which is essential given the lack of an output schema. 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 description, combined with a fully-described schema, is nearly complete for safe invocation. It provides the purpose and return shape, which compensates for the missing output schema. However, it omits any mention of the order-linkage requirement (order_id vs. order_external_id) and multi-site variations, so it falls slightly short of being fully self-sufficient.

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

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

With schema description coverage at 100%, the baseline is 3. The description only repeats parameter names (amount, type, status, paid_at) without adding new semantic detail. It does not clarify, for instance, whether order_id or order_external_id must be provided or the relationship between the two, leaving the schema to carry full parameter meaning.

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

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

The description uses a specific verb ('Record') with a clear resource ('a payment against an order') and lists key attributes (amount, type, status, paid_at). It clearly distinguishes this from siblings like order_payment_edit, order_payment_delete, and create_order by focusing on the payment-recording 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 the tool is for adding payments to orders but provides no explicit guidance on when to use it versus alternatives (e.g., order_payment_edit/delete). It also does not mention any prerequisites such as needing an order_id or order_external_id, leaving the choice of order identifier to be inferred from the schema.

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 the return value '{success}', which is not present in annotations. However, it does not disclose other behavioral traits such as permanence, cascading effects, or error conditions. The destructiveHint annotation already covers the destructive nature, lowering the bar.

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 with no redundant information. Every word earns its place, making it highly concise and effective.

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

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

For a simple delete operation with one parameter and no output schema, the description provides the essential information: what it does, the parameter, and the return shape. It could mention error handling or irreversibility, but the destructive annotation covers the key risk.

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 documents the 'id' parameter as 'Payment ID to delete', and the description merely reiterates 'by id'. With 100% schema coverage, the description adds no additional meaning or constraints beyond what is already structured.

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'), the resource ('order payment'), and the scope ('by id'). It distinguishes from sibling tools like order_payment_create and order_payment_edit by specifying deletion.

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

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

The description implies usage (when you need to delete an order payment) but does not explicitly state when to use versus alternatives, nor does it mention any exclusions or prerequisites. The destructive annotation provides some context but comes from structured data, not the description.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds no safety-related disclosure. The description does reveal the return format ({success}) which is useful since no output schema exists, but it does not elaborate on side effects, permissions, or edge cases. With annotations covering the basic mutation profile, a midpoint score is appropriate.

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

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

The description consists of two short sentences that efficiently convey purpose and return value. There is no redundancy or fluff, and the content is front-loaded with the action verb, making it easy to scan.

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

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

Given that the input schema thoroughly documents all parameters and annotations are present, the description covers the core purpose and return value. It does not mention the site parameter or any behavioral nuances, but with complete schema coverage and a straightforward operation, the description is adequately complete for an AI agent to invoke the tool correctly. Slightly reduced because it omits potential prerequisites or side effects.

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

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

The input schema provides descriptions for all 100% of parameters, so the schema already documents the meaning of each field. The description only repeats the field names without adding new semantic insight, meeting but not exceeding the baseline expected when schema coverage is high.

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 the specific verb 'Edit' with the resource 'order payment' and explicitly lists the editable fields (amount/status/paid_at), clearly distinguishing it from sibling tools like order_payment_create and order_payment_delete. The purpose is unambiguous and self-contained.

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 existing payments but does not provide explicit guidance on when to use this tool instead of alternatives. It lacks any mention of exclusions or prerequisites (e.g., site requirement for multi-site API keys) or references to related sibling tools, so the usage context is only implied.

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

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

Annotations provide readOnlyHint=true, and the description adds meaningful behavioral context: it supports incremental sync via filter_since_id and a date window, and it returns {history[], pagination}. This goes beyond the annotation by explaining the sync mechanism and return structure, without contradicting the read-only hint.

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 concise sentences, front-loaded with core purpose and followed by a compact return shape. 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?

For a read-only list tool with no output schema, the description adequately provides the return shape ({history[], pagination}) and highlights the incremental sync capability. It does not detail the fields within each history entry, but given the schema already covers all parameters and annotations confirm read-only safety, the description is 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?

The input schema has 100% coverage with descriptive parameter definitions for all 7 params. The description reinforces the purpose of filter_since_id and the date window but does not add new parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as returning order change history with status transitions, which distinguishes it from siblings like list_orders and customers_history. However, it lacks an explicit verb (e.g., 'Retrieve'), relying on the noun phrase 'Order change history' to convey the 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 by mentioning 'incremental sync via filter_since_id and a date window', which tells users when this tool is useful (for syncing changes). It does not explicitly state when to use this over alternatives like get_order or list_orders, nor any when-not-to-use conditions.

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 readOnlyHint=true, and the description adds the return structure '{offers[], pagination}' and the effect of details:true. This goes beyond the annotation by explaining what the tool returns and a key behavioral nuance. No contradictions.

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

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

The description is three short sentences: core purpose, a usage tip for details, and the return envelope. Every sentence is front-loaded and earns its place with zero fluff.

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

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

For a read-only list tool, the description sufficiently conveys the top-level return shape and a key parameter behavior. Since there is no output schema, the return format is minimally specified but adequate for the simple resource. It could benefit from more detail on the offers[] structure, but it is not necessary.

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

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

The schema covers all 6 parameters with 100% description coverage. The description's mention of details:true is redundant with the schema description ('Include per-store breakdown (sets filter[details]=1)'). It adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Stock levels (and cost prices) per offer/warehouse.' This identifies the resource and data type, and distinguishes it from sibling tools like list_costs or list_stores by focusing on inventory levels.

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 usage guidance for a specific parameter ('Use details:true for the per-store breakdown') but does not explicitly state when to use this tool over alternatives like list_costs. It gives clear context for the details option but lacks exclusions or alternative references.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the return format '{success, id}', which is useful given no output schema. However, it does not disclose additional behavioral details like required permissions or side effects beyond creation.

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

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

The description is two sentences, front-loaded with the action, and contains no filler. 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?

With full schema coverage and annotations, the description is largely complete. It adds the return format '{success, id}' which is not available from an output schema. It lacks explicit usage guidance, but that is a separate dimension and not critical for this simple create 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?

The schema has 100% parameter description coverage, so the baseline is 3. The description mentions some parameters (text, datetime, performer, order/customer) but does not add meaning beyond what the schema already provides.

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

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

The description explicitly states 'Create a task' with a specific verb and resource, and lists key fields (text, due datetime, performer, linked order/customer). This clearly distinguishes it from sibling tools like tasks_edit and tasks_list.

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

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

The description provides no guidance on when to use this tool versus alternatives such as tasks_edit or tasks_list. It merely states what the tool does, without any contextual or exclusionary 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds the return value '{success}' and the specific 'mark it complete' behavior, which provides some extra context, but doesn't go into details like partial updates or 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 two short sentences, front-loaded with the core action and ending with the return value. Every word is purposeful with no redundancy or 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?

Given the tool's simplicity, full schema coverage, and annotations, the description covers the essential behavior and return value. It doesn't explicitly state that unmentioned fields remain unchanged, but that is typically inferred for edit tools, and the schema's optional fields handle it. A minor gap is not explaining the format of '{success}', but this is acceptable.

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 all 7 parameters are documented in the schema. The description mentions 'mark it complete' which maps to the 'complete' parameter, but the schema already describes this, so the description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states 'Edit a task or mark it complete', identifying the specific action and resource. It distinguishes itself from sibling tools like tasks_list and tasks_create by focusing on editing existing tasks.

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

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

Usage is implied through the description's verb ('edit') and the sibling tool names, but there is no explicit guidance about when to use this tool versus alternatives. For example, it does not say 'use tasks_create for new tasks'. This makes it clear but not fully 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?

The readOnlyHint annotation already signals a safe read operation; the description adds value by stating the return structure {tasks[], pagination}, which is useful behavioral context beyond the annotation. No contradictions.

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

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

The description is a single sentence that packs the core purpose, filters, and return type without any redundancy or extra fluff.

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

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

For a simple list tool with no output schema, the description covers the essential aspects: purpose, filters, and return shape. Combined with the readOnlyHint annotation, it provides sufficient context for safe invocation, though it could optionally mention pagination defaults (already in schema).

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

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

Schema description coverage is 100% and each parameter is already well described. The description merely paraphrases filter categories (status/performer/customer) without adding new meaning or clarifying the enum values 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 'List' with a clear resource 'follow-up tasks/reminders' and specifies filtering criteria. It distinguishes this from sibling task tools like tasks_edit and tasks_create by indicating it is for listing/reading.

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

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

The description implies the tool is for read-only listing and gives filter context (status/performer/customer), which helps agents know when to use it. However, it does not explicitly mention alternatives or when not to use it, such as pointing to tasks_create/edit for modifications.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable context beyond this: partial-update behavior ('Only the fields you pass are sent') and the return shape ('Returns {success}'). It does not conflict with annotations and provides meaningful transparency for a non-destructive update 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 two sentences, front-loaded with the action and resource, and every word contributes. It states the scope, lookup options, partial-update behavior, and return value with zero waste.

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

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

For an 11-parameter tool with no output schema, the description provides essential context: lookup method (id/externalId), partial update semantics, and return type. It omits the multi-site 'site' nuance, but that is already covered in the schema's parameter description, so the tool definition remains adequately complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the crucial semantic that only provided fields are sent, which clarifies the optional nature of all non-required parameters and how updates merge with existing data. This goes beyond the schema's per-field 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 uses a specific verb ('Edit') with a clear resource ('existing customer') and enumerates updatable fields (name, email, phones, address). It distinguishes from sibling tools like create_customer and merge_customers by explicitly targeting existing customer updates and supporting lookup by id or externalId.

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 use when editing an existing customer, and the partial-update statement ('Only the fields you pass are sent') provides key usage guidance. It does not explicitly name alternatives or exclusions, but the sibling tool names (create_customer, merge_customers) make the intended use case obvious.

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=false), the description discloses a key behavioral trait: 'Only the fields you pass are sent', indicating a partial update rather than full replacement. It also states the return value ({success}), providing 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 groups relevant field categories. It does not waste words, and the additional clause about partial updates earns its place by conveying critical behavior.

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 15-parameter mutation tool with no output schema and annotations present, the description covers the essential context: what the tool does, its partial-update behavior, and the return value. The schema handles parameter details, so the description is suitably complete without over-explaining.

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 descriptions cover all 15 parameters with 100% coverage, so the description adds little per-parameter meaning. However, the phrase 'Only the fields you pass are sent' clarifies the semantics of omitted parameters (they remain unchanged), which is a useful addition more than just schema repetition.

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 (update an order) and the scope (status, customer, delivery, comments), which distinguishes it from siblings like create_order or list_orders. The verb 'update' with a specific resource 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 implicitly indicates when to use this tool (to modify an existing order) relative to siblings like create_order or get_order. It does not explicitly exclude alternatives or mention conditions, but the name and scope make the usage context clear enough.

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