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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the exact response shape (yes/no plus enumerated reasons: out of stock, insufficient quantity, inactive, unknown SKU), which an agent needs to interpret results. It omits any auth or rate-limit 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?

Three compact sentences, front-loaded with the core question, then the return contract, then the usage trigger. No filler; every sentence earns its place.

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

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

An output schema exists, so return values need not be re-explained, yet the description still summarizes the reason codes usefully. Annotations cover safety and the schema covers parameters, so the definition is nearly complete; the only minor omission is any hint about latency, batch limits, or behavior when a location name is invalid.

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

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

Schema description coverage is 100% – both 'lines' and 'location_name' are documented in the schema, including the 25-line cap and the location scoping behavior. The description adds no parameter-level meaning beyond that, 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?

States a specific verb and resource ('Can these SKUs be sold right now?') and explicitly enumerates the return semantics (sellable yes/no with a per-SKU reason). It is clearly distinguishable from generic item tools like list_items or get_item because its purpose is sellability, not retrieval.

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?

Gives an explicit trigger: 'Call this before an agent pitches, recovers or promises any product to a customer.' That is strong when-to-use guidance. It does not name when not to use it or point to a sibling for the alternative case, so it falls 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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds the valuable behavioral trait that this operation costs no Zoho API calls, which is not in the annotations. It does not go into auth details beyond granted scopes, but that is acceptable given the annotation coverage.

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

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

Two sentences, perfectly sized. The first sentence front-loads the returned information; the second adds a key behavioral benefit. 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 parameterless, read-only status tool that has an output schema, the description is complete enough. It tells the agent what it will learn and that the call is free, and the annotations cover the safety profile. 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 tool takes no parameters, so the schema description coverage is trivially 100%. Per the rules, a zero-parameter tool receives a baseline of 4 for parameter semantics. There is nothing further the description needs to add.

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 exactly what the tool reports: the connected Zoho organization, granted scopes, and remaining per-minute/daily API budget. It is clearly distinct from sibling tools that retrieve business objects (items, sales orders, availability). The only minor gap is the lack of an explicit verb like 'Returns', but the resource and scope are 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 tool is a diagnostic status check, so its use is somewhat implied. The sentence 'Costs no Zoho API calls' hints that it can be called freely, but the description does not explicitly say when to use it versus alternatives, nor does it state any prerequisites such as needing an existing connection.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description's extra content is mostly about the return payload (verdicts, summary, gaps), which is output-schema territory rather than behavioral disclosure, and it says nothing about aggregation cost, freshness, or how identifiers resolve.

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 the resource and its contents, with the usage cue last. The verdict enumeration is long but genuinely informative, so there is little 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?

With rich annotations and an output schema, the description need not explain return format, and it sensibly focuses on scope and use cases. It falls just short of full completeness by not noting that all three identifier parameters are optional and at least one must be supplied.

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 three identifiers (salesorder_id, reference_number, salesorder_number) are already documented, making the baseline 3 appropriate. The description adds no guidance on which identifier to supply or whether one is required.

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

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

The description states a specific verb and resource ('Proof-of-fulfilment pack for one order') and enumerates exactly what the pack contains (shipments, carrier, AWB, dates, items, verdict, summary, gaps). This clearly distinguishes it from siblings like get_sales_order or list_sales_orders, which return order data rather than an evidence pack.

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?

'Use for chargebacks/disputes and “where is my order” questions' gives explicit and concrete when-to-use context. It does not name alternatives or when-not conditions, but the intended scenarios are unambiguous.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine content context by stating the response includes per-warehouse stock, but says nothing about auth, rate limits, or behavior when an identifier matches nothing.

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

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

Two short sentences, front-loaded with what is returned and followed by the identifier rule. No filler, no repetition of the name 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?

With rich annotations and an output schema present, the description need not explain return values or safety. It covers the identifier contract and the payload shape, which is enough to call the tool correctly; only the sibling-routing guidance is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema does not express: the schema makes both params nullable with no required list, while the description mandates exactly one of item_id or sku. That is meaningful guidance the structured fields lack.

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?

Specific verb and resource: returns full detail for one item, plus the scope of the payload (stock per warehouse/location). This distinguishes it from list_items and search_items, though it never names those siblings explicitly.

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?

"Give exactly one of item_id or sku" is an invocation constraint, not a when-to-use rule. The description never says when to pick this over check_availability or search_items, leaving the routing decision entirely to inference.

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, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description adds useful context: the response includes line items and masked customer contact. Beyond that, it doesn't disclose auth requirements, error behavior for failed lookups, or rate limits, so it adds moderate value on top of solid 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 tight sentences, front-loaded with what is returned and followed by the input constraint. 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?

An output schema exists, so return-value explanation isn't required, and annotations carry the safety profile. Combined with a summary of returned fields and the one-identifier constraint, this is nearly complete; the only gap is an explicit sibling routing statement.

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

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

Schema description coverage is 100%, so the schema fully documents the three identifier parameters. The description's 'Give exactly one identifier' reinforces exclusivity but adds no format or syntax detail beyond what the schema provides; 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?

States a specific verb (get) and resource (sales order) and enumerates the returned content (line items, shipped quantities, packages, masked customer contact), clearly distinguishing this single-record fetch from sibling list_sales_orders and search_sales_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 instruction 'Give exactly one identifier' implies usage as a single-record lookup, and the contrast with list/search siblings is discernible from the name. It does not explicitly state when not to use it or name the human-readable alternative, but the constraint is clear.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's real contribution is the aggregation semantics: stock levels are combined across all warehouses, which the annotations cannot express. It does not restate destructive/read-only behavior, and pagination behavior is carried by the schema, so this is a genuine value-add without being exhaustive.

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

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

Two short sentences, front-loaded with what the tool returns and scoped immediately, then the alternative. No filler or restated parameter names.

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 an output schema present, return values need not be described, and the description covers scope, contents, use case, and the correct alternative. Nothing an agent needs to invoke this correctly 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?

Schema description coverage is 80%, so the schema already documents cursor, status, page_size, and low_stock_only. The description only implicitly gestures at low_stock_only through the 'running low' example and adds no syntax or defaulting detail beyond the schema, so the 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?

Specific verb ('Browse') plus resource ('the merchant's catalogue') with the added scope 'stock levels (all warehouses combined)'. It names the sibling check_availability as the non-overlapping alternative, so an agent can route between the two without opening either schema.

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

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

Explicit when-to-use is given ('overviews such as "what is running low?"') along with the alternative for specific SKUs (check_availability), which is strong routing guidance. It does not differentiate from search_items, the other plausibly overlapping sibling, so it falls short of a full when/when-not map.

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 readOnly, idempotent, non-destructive, open-world semantics, so the safety profile is covered. The description adds one genuinely useful behavioral fact, the newest-first ordering, but says nothing about result volume or how pagination terminates beyond what the cursor schema states.

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

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

A single front-loaded sentence with no filler; the default ordering constraint appears immediately and the optional filters follow.

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?

An output schema exists, so return values need no explanation, and the filters are fully specified by the schema. The definition is nearly complete; only the relationship to the sibling search tool is left unstated.

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 cursor, status enum, date_from/date_to formats, and page_size bounds are all documented in the schema. The description only restates the status and date-range filter categories, adding no syntax or defaults beyond what is already structured. 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 names a specific verb (Browse) and resource (sales orders) plus the default sort order, so the operation is unambiguous. It does not explicitly distinguish itself from the sibling search_sales_orders, leaving the list-vs-search boundary to inference.

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: browse when you want a full listing with optional status/date filters, as opposed to the sibling search tool. There is no explicit statement of when to prefer this over search_sales_orders or what prerequisites apply, so guidance is only adequate.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds nothing about result ordering, case sensitivity, or empty-result behavior, and pagination is only covered by the schema's cursor/page_size docs.

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

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

A single front-loaded sentence with the action first and the qualifying condition second. 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?

With an output schema present and rich annotations, the description need not explain return values or pagination. It is complete enough to call correctly, though naming the exact-match alternative would close the last gap.

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

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

Schema description coverage is 100% and all five parameters (including the field/match enums and pagination) are fully documented in the schema. The description adds no semantics beyond what the schema already provides, so the 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?

States a specific verb ('Find') and resource ('items') plus the match basis (partial name or SKU). It implicitly contrasts with exact-SKU lookup, but it never names the sibling (get_item) that handles the exact case, so an agent must infer the boundary.

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?

Gives a clear trigger condition: use when you do not know the exact SKU. That implicitly routes exact lookups elsewhere, but no sibling tool is named explicitly and no exclusions (e.g. vs list_items) are 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds only the minimum-one-criterion requirement and nothing about result volume, ranking, or matching behavior; pagination is documented in the schema rather than the description.

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

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

Two short sentences, front-loaded with the resource and searchable dimensions, then the constraint. No filler, though it is minimal enough that it leaves value on the table.

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

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

With a rich output schema, full annotation coverage, and complete parameter documentation, the description does not need to explain return values or pagination. It is complete enough to call correctly, with only sibling differentiation 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?

Schema description coverage is 100% with all 8 parameters documented individually (formats, ranges, defaults), so the schema carries the load. The description names the same searchable fields (reference number, order number, customer, text) without adding syntax or precedence detail, matching the baseline for high 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?

States a specific verb (find/search) and resource (sales orders) plus the searchable fields, so the agent knows this is a lookup tool. It does not distinguish itself from siblings like list_sales_orders or get_sales_order, so it falls short of a 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?

"Give at least one criterion" is a useful invocation constraint, implying the search needs a filter and is not a bare list. However, there is no guidance on when to use this versus list_sales_orders or get_sales_order, so usage is only implied.

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