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

The description confirms the read-only nature already indicated by the readOnlyHint annotation. It adds no further behavioral traits (e.g., authentication, rate limits, or side effects). Minimal additional transparency beyond the annotations.

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

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

The description is extremely concise: two sentences that deliver the core purpose and usage guidelines without any wasted words. It is front-loaded with the key action.

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

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

Despite having an output schema and annotations, the description fails to explain the key parameters (4 params, 0% schema coverage). This leaves a significant gap for the agent in correctly invoking the tool. The description should have included parameter semantics.

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 4 parameters with 0% description coverage in the schema. The tool description provides no explanations for offer_ids, page_token, limit, or business_id, leaving the agent without guidance on how to use these 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 verb 'Get' and the resource 'current bids at business level'. It distinguishes from sibling tools by explicitly naming alternatives (ym_execute with actions for suggestions and updates).

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

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

The description explicitly tells when to use this tool (to get current bids) and when to use alternatives (ym_execute with bid_recommendations or bids_update). This provides clear usage 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. Description adds return format (array of {id, domain, placementType}), providing value beyond annotations. No additional behavioral traits like pagination are mentioned, but given zero parameters, this is reasonable.

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, front-loaded with action and resource, every word adds value. 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 simple list with no parameters and existing annotations, the description covers purpose, return structure, and sibling alternative. Minor omission: ym_campaign is not listed in sibling tools, but it's clearly referenced. Overall, adequate 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?

No parameters present; schema coverage is 100% by default. Baseline score of 4 applies since description adds nothing about parameters but is not expected to.

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

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

Description clearly states it lists all campaigns (shops) in the account, with specific verb 'List' and resource 'campaigns'. It also distinguishes from sibling ym_campaign by noting usage for single campaign details.

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

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

Explicitly tells when to use the alternative tool ym_campaign for single campaign details, providing clear context. Lacks explicit 'when not to use' but the alternative 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, and the description is consistent. However, it adds no additional behavioral context beyond 'list', such as pagination behavior, scope of chats, or authentication needs. With annotations, 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 sentences, no wasted words. Purpose stated first, then usage guidance. 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?

While an output schema exists, the input parameters are completely undocumented in both schema and description. The description lacks details on the purpose of business_id, pagination via page_token, and the default limit. This makes the tool less complete for an agent to use correctly.

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

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

Schema description coverage is 0%, and the description provides no information about the three parameters (page_token, limit, business_id). The description fails to compensate for the lack of schema 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 'List buyer chats', which is a specific verb+resource. It distinguishes from sibling tools by directing to use ym_execute for chat messages/reply.

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

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

Explicitly tells when to use alternatives: 'Use ym_execute with action chat_history for messages, chat_send to reply.' Provides clear context for this tool vs others.

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

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

Annotations already indicate readOnlyHint=false, so description adds only that params_json is validated against action schema. No disclosure of side effects, auth requirements, or irrevocability. Adequate but not rich beyond annotations.

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

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

Two concise sentences with front-loaded purpose and immediate usage hint. No extraneous information.

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

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

Output schema exists, so return values are covered. The description gives minimal but sufficient context for a single required parameter tool, though leaves ambiguity about action identifiers. Somewhat complete but not comprehensive.

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

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

Schema coverage is 0%, so description must compensate. It mentions 'action by ID' and 'params_json' but does not explain parameter format, valid action IDs, or how to structure params_json. The validation hint is vague; more concrete schema details are missing.

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

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

Clearly states 'Execute action by ID' – specific verb and resource. Distinguishes from sibling ym_search (discovery) and other tool prefixes (ym_bids, etc.).

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

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

Explicitly instructs to 'Use ym_search to discover actions and their schemas first', providing prerequisite context. Does not elaborate on when not to use or alternative execution tools, but the guidance is clear and actionable.

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=false, implying mutation. The description adds the `output_path` constraint but does not disclose other behavioral traits like authentication needs, rate limits, or what happens if the path is invalid.

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

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

The description is very short (two sentences) and front-loaded with purpose. However, it omits crucial details about parameters, so it is not optimally concise—missing information forces extra cognitive load.

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

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

Despite having an output schema, the description does not mention what the tool returns. For a file download tool, expected output (e.g., file path, metadata) is important. The description is incomplete for agent decision-making.

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

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

Schema description coverage is 0%. The description explains `output_path` constraint but does not explain the `action` parameter (e.g., what actions are available) or `params_json`. This is insufficient for a tool with three 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 tool downloads a file (PDF/binary), distinguishing it from sibling `ym_execute` which likely performs other actions. The verb 'downloads' and resource 'file' specify the core functionality.

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

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

No guidance is given on when to use this tool vs alternatives. It only mentions a path constraint, but does not explain prerequisites or when not to use it.

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

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

Annotations already provide readOnlyHint=true, so the description doesn't need to emphasize safety. It adds behavioral context about pagination and directs to another tool for comments, which is helpful. 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?

Two sentences, no wasted words. The core purpose is front-loaded, and the additional instruction about comments is concise and relevant.

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

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

The description is too brief. It does not explain the parameters (business_id, page_token, limit) despite 0% schema coverage. While an output schema exists, the agent lacks guidance on how to use the pagination parameters or the importance of business_id. Essential details are missing for a tool with three parameters.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does not mention page_token, limit, or business_id at all. The description fails to add any meaning beyond the schema names.

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: 'Get product reviews/feedbacks.' It uses a specific verb ('Get') and resource ('reviews/feedbacks'). The mention of pagination adds specificity. It distinguishes itself from sibling tool ym_execute by redirecting for comments.

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: it is for getting reviews/feedbacks with pagination. It explicitly tells when to use ym_execute for comments, offering an alternative. However, it does not specify when not to use this tool or additional exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, and description confirms it's a listing operation. Adds pagination context and return fields, but no additional behavioral traits like rate limits or auth requirements.

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

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

Two sentences with no redundancy: first sentence states purpose and output, second gives usage guidance and alternative. Efficient and front-loaded.

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

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

Output schema exists, so return values are covered. However, parameter descriptions are insufficient for a 4-param tool with 0% schema coverage. Missing details for offer_ids and business_id limit completeness.

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

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

Schema coverage is 0%; description only hints at pagination parameters (page_token, limit) but does not explain offer_ids or business_id. The description partially compensates for pagination but leaves other parameters undocumented.

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

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

Clearly states it lists products (offer mappings) at business level, returns specific fields (SKU, name, category, mapping status), and is paginated. Distinguishes from sibling ym_execute by noting it handles campaign-level offers.

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

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

Explicitly says when to use (business-level offers) and provides alternative for campaign-level offers via ym_execute. No explicit when-not-to-use, but the alternative is clear.

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

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

The description does not contradict the readOnlyHint annotation. It adds some behavioral context by listing the categories of details included, which is beyond what the annotation provides. However, it does not disclose any additional traits such as data freshness, rate limits, or prerequisites.

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

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

The description is two sentences long, front-loads the purpose, and immediately follows with usage guidance. Every word serves a purpose, making it 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 tool's simplicity (2 parameters, has output schema), the description adequately covers the tool's purpose and usage context. The lack of parameter explanation is a minor gap, but the output schema handles return values.

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

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

The schema description coverage is 0%, and the description does not explain the parameters (order_id, campaign_id) beyond what their names imply. It omits details such as campaign_id being optional with a default of 0, which would help the agent invoke the tool correctly.

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

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

The description starts with 'Get full order details', clearly stating the verb and resource. It lists the types of details (items, delivery, buyer info, status history) and distinguishes from the sibling tool ym_orders by noting that ym_orders is for searching/filtering multiple orders.

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

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

The description explicitly tells when to use this tool (to get full order details) and when to use the alternative (ym_orders to search/filter multiple orders). This provides clear guidance on tool selection.

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

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

Annotations declare readOnlyHint=true, consistent with description. Description adds behavioral details (optional status filter, pagination) beyond annotations. No mention of auth needs or rate limits, but annotations already cover safety profile adequately.

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

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

Description is three sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Given 4 parameters, optional status filter and pagination are covered, but 'campaign_id' parameter is unexplained. Output schema exists so return values are handled. Adequate but not fully comprehensive.

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

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

Schema description coverage is 0%, so description must compensate. It partially covers 'status' by listing valid values but does not mention 'page', 'page_size', or 'campaign_id'. Only adds marginal value over schema for one of four 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?

Description clearly states 'List orders' with optional status filter, lists all status values, mentions pagination, and distinguishes from sibling 'ym_order' for single order details. This provides specific verb+resource with good 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?

Description explicitly says 'Use ym_order for single order details', offering direct guidance on when to choose an alternative. However, it does not cover when not to use this tool or mention other alternatives among many siblings.

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

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

Description adds the typical state flow (PROCESSING → DELIVERY → DELIVERED) and mentions substatus as optional, which goes beyond the readOnlyHint annotations. However, it does not disclose any potential side effects, permissions, or transition constraints.

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

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

Three concise sentences with no fluff: states purpose, provides flow and args, then gives usage guidance. Front-loaded with the core action.

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

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

Adequate for a simple update tool given an output schema exists, but incomplete parameter documentation and lack of details on allowed status values or transition rules limit its completeness.

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

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

With 0% schema coverage, description should explain all parameters. It mentions 'status' and 'substatus' with context, but misses the required 'order_id' and optional 'campaign_id' parameters, leaving their meaning and usage unclear.

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

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

Clear verb 'Update' with resource 'order status'. Distinguishes from siblings by providing typical flow and explicitly mentioning alternative tool (ym_execute) for batch operations. No ambiguity.

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

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

Explicitly states when to use this tool (single order status update) and when to use an alternative (ym_execute for multiple orders). Provides typical flow states as guidance.

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

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

Annotations already mark readOnlyHint=true, so the description's mention of 'Get' aligns with that. It adds context about returning current prices and currency, though it does not detail pagination or other behaviors. Still, with annotations covering safety, a 4 is warranted.

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 concise sentences with no wasted words. Front-loaded with purpose and returns, then usage guidance.

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

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

Despite having an output schema, the description lacks parameter explanations which are essential given 0% schema coverage. It does not mention pagination or filtering, leaving significant gaps for a 4-parameter tool.

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

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

Schema description coverage is 0%, yet the description provides no explanation of the 4 parameters (offer_ids, page_token, limit, business_id). It fails to add any meaning beyond the schema's names and defaults.

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

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

The description clearly states the verb 'Get' and resource 'product prices at business level', and specifies that it returns current prices and currency. It also distinguishes itself from sibling tool ym_execute for campaign-level prices.

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

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

Explicitly states when to use (business-level prices) and when not to (campaign-level), providing an alternative: 'Use ym_execute with action campaign_offers for campaign-level prices.'

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

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

The annotation already indicates it's a write operation (readOnlyHint=false). The description adds no further behavioral context like authorization needs, side effects, or rate limits.

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

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

The description is very short with one sentence and a parameter note. It avoids unnecessary words, but the conciseness comes at the expense of completeness.

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

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

For a write operation, the description omits expected return values, prerequisites, and error scenarios. The presence of an output schema reduces the burden slightly, but the description should still provide context.

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

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

Schema description coverage is 0%. The description adds format details for 'prices_json' (JSON array with specific fields) but does not mention 'business_id' at all, leaving its purpose unclear.

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 'Update product prices' as a specific action on a specific resource. It differentiates from sibling 'ym_prices' which is likely for reading. However, it doesn't explicitly distinguish from other update tools like 'ym_stocks_update'.

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

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

No guidance on when to use this tool vs alternatives. The phrase 'Business-level operation' is vague and doesn't help the agent decide.

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

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

Annotations indicate the tool is not read-only (readOnlyHint=false). The description adds that the operation is asynchronous and returns a reportId for polling. However, no details are given about permissions, side effects, or failure modes.

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

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

The description is concise with two sentences, front-loading the primary action and result. The list of report types is succinct and well-placed. No redundant text.

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

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

Despite the tool having an output schema (not shown in input), the description fails to explain the payload_json parameter or usage context. For an async report generation tool, more details on the polling process, expected delays, or error handling would be needed for completeness.

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

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

The schema has 0% description coverage, requiring the description to add meaning. The description lists valid values for report_type, partially compensating. However, payload_json remains undocumented with no guidance on its structure or purpose.

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 'Start async report generation' with a specific verb and resource, and lists supported report types. It provides a clear purpose but does not explicitly differentiate from sibling tools beyond mentioning polling with ym_execute.

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 lacks guidance on when to use this tool versus alternatives. It does not specify prerequisites, when-not to use, or alternative report tools. The mention of polling with ym_execute is helpful but insufficient.

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 description's mention of 'paginated' adds some behavioral context but does not disclose rate limits, authorization needs, or default behavior for campaign_id=0.

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 with no wasted words, front-loading the core purpose and then providing usage guidance.

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

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

Despite having an output schema, the description does not explain what a 'return' is, what fields are included in the listing, how pagination works (e.g., total count, next page), or the significance of campaign_id defaulting to 0. This is insufficient for a 3-parameter tool with no parameter docs.

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 0% schema description coverage, the description fails to explain any of the three parameters (page, page_size, campaign_id), leaving the agent without meaningful semantic guidance beyond their names and defaults.

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

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

The description clearly states 'List returns for a campaign,' which is a specific verb+resource. It also mentions pagination and distinguishes itself from ym_execute, which is used for single return details.

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

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

Explicitly directs the agent to use ym_execute with action return for single return details, providing clear when-to-use vs. alternative 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, which aligns with 'Find available actions' and returning data. The description adds no further behavioral details 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 concise with two sentences and a list of domains, but the list is somewhat lengthy and could be more structured.

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

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

Given the existence of an output schema, the description adequately explains what is returned (action ID, description, parameters schema). It does not mention pagination or limits, but overall is 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?

With 0% schema coverage, the description partially compensates by explaining 'query' is for intent and 'domain' is a filter with listed options. However, it lacks details on input format or constraints.

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 'Find available actions by intent' and lists optional domain filters, which distinguishes it from sibling tools that are specific actions.

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 discovering actions based on intent, and the optional domain filter provides context. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations declare readOnlyHint=true, and the description uses 'List' which aligns with that. However, the description adds no further behavioral context such as rate limits, authentication needs, or what happens when called without parameters. 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?

Two sentences, highly concise. The first sentence states the main purpose, the second provides usage guidance. Every sentence adds value without redundancy.

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

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

While an output schema exists (so return values need not be explained), the description leaves the campaign_id parameter unexplained and does not define 'first-mile shipments'. For a simple tool, basic completeness is lacking.

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

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

The single parameter campaign_id has no description in the schema (0% coverage), and the tool description does not explain its purpose or how it affects results. The description must compensate for missing schema coverage but fails to do so.

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 'List first-mile shipments', clearly indicating the verb (list) and resource (shipments) with a specific scope (first-mile). It differentiates from sibling tools by noting that advanced filtering is available via ym_execute.

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

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

The description provides explicit guidance: use this tool for simple listing of first-mile shipments, and use ym_execute with action shipments_search for advanced filtering. This helps the agent choose the correct tool.

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

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

The annotation readOnlyHint: true already indicates non-destructive behavior. The description adds that it 'returns warehouse stocks per SKU', which is mildly helpful but does not disclose other behavioral traits like pagination limits or authentication needs. With annotations present, the description provides only modest added 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 two sentences with no fluff. The purpose is stated upfront, and the alternative is mentioned. Every word adds value.

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

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

Despite having an output schema, the description does not detail return format or pagination behavior. The three parameters lack any explanation of their purpose or constraints. The tool is simple, but the omission of parameter semantics makes it incomplete for an agent to use 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?

Schema description coverage is 0%, so the description must compensate but fails to describe any parameters. The three parameters (page_token, limit, campaign_id) are not explained in the description, leaving the agent to rely on parameter names alone. This is inadequate for correct invocation.

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

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

The description clearly states 'Get product stocks for a campaign. Returns warehouse stocks per SKU.' This specifies the action (get), resource (stocks), and scope (per SKU, per warehouse), and distinguishes it from the sibling ym_stocks_update which handles stock changes.

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 includes 'Use ym_execute with action stocks_update to change stock quantities.' This explicitly tells the agent when to use an alternative tool for modification, clarifying that this tool is for reading only.

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 says 'update', implying a mutation, which aligns with the readOnlyHint=false annotation. However, it does not disclose any behavioral traits such as authorization requirements, side effects (e.g., overwritten data), rate limits, or error behavior. The absence of annotations leaves the description solely responsible, and it falls short.

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

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

The description is extremely concise, using two sentences to convey purpose and argument structure. It is front-loaded and contains no redundant information.

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

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

Given the tool has an output schema, the description need not detail return values. However, for a mutation tool with two parameters (one undocumented), the description is too minimal. It omits details like batch behavior, error handling, and prerequisites, making it insufficient for an agent to use confidently.

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

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

The description explains the structure of the required 'stocks_json' parameter (JSON array with specific fields), which adds meaning beyond the raw string type in the schema. However, the optional 'campaign_id' parameter is not mentioned, and with 0% schema description coverage, the description only partially compensates.

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

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

The description clearly states the tool updates product stocks, which is a specific verb-resource combination. However, it does not differentiate from sibling tools like ym_stocks (likely a read) or ym_prices_update, leaving ambiguity about when to use this over related 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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.

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