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

The annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, externally visible operation. The description adds the approval precondition and the failure conditions, which is real value beyond the annotations, but it never says what actually changes when the proposal is applied or whether the effect is reversible.

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 action, and every clause carries information about preconditions or failure modes. There is 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 destructive, irreversible-sounding mutation with no output schema, the definition covers when the call fails but leaves open what the return value is and what the side effects on orders, stock, prices, or refunds will be. Adequate to avoid misuse, but not 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 coverage is 0% and the single required parameter proposal_id is never explained in the description. It does not say where the identifier comes from (e.g., a prior propose_* call or list_proposals), nor what the minLength constraint implies, so the description adds nothing over the bare 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?

"Executes a proposal that a human has approved" gives a specific verb (executes) and resource (proposal) and implicitly separates this tool from the propose_* siblings and list_proposals. It stops short of naming an alternative, but the action is unambiguous.

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

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

It states a clear precondition (only after human approval) and two negative conditions (pending/rejected proposals, read-only servers) that tell the agent when the call will not work. What is missing is any pointer to checking status via list_proposals before calling.

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 openWorldHint=true, so the safety profile is covered. The description adds useful context about the shape of the payload (line items, shipping, payment, notes) beyond the annotations, but says nothing about error behavior for missing ids or whether the record is scoped to a store/workspace.

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

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

A single compact clause with zero filler, front-loading the resource and its returned contents. It is a fragment rather than a sentence, but nothing is wasted.

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's brief enumeration of returned sections carries part of the burden, but it does not explain the id semantics or error cases for a lookup tool that can legitimately fail. Adequate but with clear gaps given the absence of both output schema and parameter documentation.

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 `id` parameter has 0% schema description coverage and the description never mentions it, so it is unclear whether this is an internal order id, an order number, or a platform-specific identifier. With low schema coverage and one parameter, the description should compensate but does not.

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 resource (one order) and enumerates what it contains — line items, shipping, payment, notes — which distinguishes it from the sibling list_orders. It omits an explicit verb, so the agent must infer 'retrieve', but the singular framing makes the read-one semantic 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?

There is no statement of when to use this tool versus list_orders or search_customers, and no mention of prerequisites or failure conditions (e.g., what happens with an unknown or deleted order id). The only differentiation is implicit in the singular noun.

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 openWorldHint=true, so safety and external-data scope are covered. The description adds one useful behavioral detail beyond that — that the payload includes a variations summary for variable products — but says nothing about not-found behavior, auth, or what "full" excludes.

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

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

A single compact sentence with no filler, and the lookup keys are front-loaded. It is slightly over-dense given how much the phrase "variations summary" has to carry, but nothing is wasted.

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 and 0% parameter coverage, the description should resolve the id-vs-SKU contract and the not-found case; it resolves neither. It does at least hint at the return shape for variable products, which keeps it from being inadequate, but an agent could still call it incorrectly by supplying both keys or neither.

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% and both parameters are bare integers/strings with no descriptions, so the description carries the full burden. It only loosely signals that id and sku are alternative lookup keys — it never says whether one is required, whether both may be supplied, or which takes precedence, which is exactly the ambiguity created by a schema with zero required fields.

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 and resource ("Full product") and states the two lookup keys (id or SKU), which clearly separates it from the sibling list_products. It falls short of a 5 only because it never explicitly names list_products as the alternative for browsing.

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 rather than stated: an agent can infer this is the single-record fetch when it already has an id or SKU. There is no explicit when-to-use/when-not or guidance on which sibling to pick when the identifier is unknown, so the guidance is only inferable.

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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context about the coupon attributes returned and the validity-checking use case, but it says nothing about pagination behavior, result limits, or authorization needs.

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 and front-loads the returned fields before the usage guidance, with no wasted wording. The opening noun fragment is slightly less clear than a complete sentence stating the list 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?

For a simple read-only list tool with no output schema, the description covers what data is returned and the primary use case. However, it leaves pagination semantics unexplained and does not clarify the listing scope, which are meaningful gaps given the low schema description coverage.

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 only 33%: code is documented as 'Exact coupon code,' while page and per_page have no descriptions anywhere. The description's 'is code X still valid?' phrasing hints that code is used for lookup, but it does not compensate for the undocumented pagination 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 identifies the resource (coupons) and the fields returned (type, amount, usage, expiry), but it uses a noun fragment rather than stating the verb 'list' or the scope of the listing. An agent must rely on the tool name and title to confirm that this is a listing operation, and there is no explicit differentiation from sibling list 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?

It gives a clear, specific use case: answer 'is code X still valid?' before proposing anything. That implicitly routes the agent toward this tool before the propose_* siblings, though it does not name an alternative or state 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 declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds no behavior of its own. It says nothing about result ordering, pagination behavior despite page/per_page existing, or result volume.

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 short sentence with the resource front-loaded and zero filler. It is grammatically a fragment and could carry one more clause of substance, but nothing is wasted.

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 7-parameter read tool with no output schema, the description covers filtering but leaves pagination defaults, result ordering, and return shape entirely undocumented. Adequate to start a call, not enough to call it 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?

Schema description coverage is only 29%, so the description must compensate, and it does partially: it clarifies that search matches order number, name, and email, which the bare schema does not. However, page, per_page, before, and the status enum values get no explanation beyond their 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 names the resource (orders) and enumerates the four filter dimensions, which lets an agent distinguish it from single-order tools like get_order and from non-order siblings such as list_products. It is a sentence fragment with no explicit verb, but the tool name supplies 'list' and the scope is unambiguous.

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

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

There is no statement of when to use this tool versus get_order, search_customers, or the propose_* siblings, and no prerequisites or exclusions. The filter list only implies how to call it, not when.

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 openWorldHint=true, so the safety profile is covered. The description adds that results are paged and include price and stock, but it omits that status defaults to 'publish' (a non-obvious scoping behavior that silently hides drafts/pending items) and says nothing about total counts or pagination 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?

Two sentences, front-loaded with the search capability and followed by the return shape. No filler, no repetition of the title, nothing that could be cut.

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 9-parameter, zero-required, low-schema-coverage listing tool with no output schema, the description covers the purpose and rough return shape but leaves the sort/pagination parameters and the default status filter unexplained. An agent could call it, but would likely miss that only published products return by default.

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 only 22% across 9 parameters, so the description has to compensate, and it does partially by naming the filterable dimensions that map to search, sku, status, category and stock_status. However it adds no meaning for page, per_page, order, orderby, nor the enum semantics or the default of 'publish' for status.

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 first sentence gives a specific verb (search) and resource (catalogue) and enumerates the filter axes: text, SKU, status, category, stock status. The second sentence adds the return shape (a page of products with price and stock). It does not explicitly differentiate itself from siblings like get_product or low_stock_products, which keeps it below 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?

Usage is only implied by the verb 'search' – an agent can infer this is the browsing/listing tool versus the single-item get_product, but the description never says so. There is no statement of when to prefer low_stock_products or get_product, and no prerequisites or exclusions are given.

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

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating read, so the description's only job is to add context beyond that. It adds almost nothing: no mention of ordering, pagination, result size, or what a returned proposal record contains. Because there is no output schema, the description is the only place this could be disclosed and it is silent.

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?

It is short and front-loaded, but it is a sentence fragment rather than a complete statement, and the sole content is a list of enum values already visible in the schema. The brevity is under-specification rather than efficiency.

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 list endpoint with no output schema and a 0%-documented parameter, the description should at minimum say it returns a collection, whether results are paginated, and how the status filter behaves. None of this is present, leaving the agent unable to predict the response shape of a tool it is expected to call.

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, and it does not. It enumerates the five status values, which is exact duplication of the enum already in the schema, but never explains that the parameter is an optional filter, nor what omitting it returns (presumably all proposals).

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 the resource (proposals) and enumerates its lifecycle statuses, which hints at a read/lookup tool, but it never supplies a verb such as 'list' or 'retrieve' and never states that this returns multiple records. The listing sense comes from the tool title and name, not from the description itself, so an agent must infer the operation from metadata rather than from prose.

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 about when to call this versus the sibling proposal tools (propose_order_note, propose_stock_update, apply_proposal) or whether it should be used before applying a proposal to find its ID. No preconditions, no exclusions, and no indication that the status argument is optional.

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 openWorldHint=true, so the safety profile is covered. The description adds real domain context beyond that: only products with 'managed' stock qualify, meaning untracked inventory is excluded, and the effective threshold can be per-product rather than global. It says nothing about ordering, pagination, or what happens when many products qualify.

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 resource first and the filter semantics in a parenthetical, with no filler. The nested parenthetical is slightly dense but every clause carries 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?

For a two-parameter read tool with no output schema, the description covers the core filter semantics but leaves both the pagination parameter and the return shape (fields, ordering, whether only managed products appear in ordering) unaddressed. It is adequate rather than 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 0%, so the description carries the burden, and it does explain `threshold` meaningfully: it is only the fallback, since each product's own low-stock amount takes precedence. However, `per_page` is never mentioned and the interaction between pagination and the result set is left unclear, so the compensation is only partial.

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 resource ('Products') and a precise filter condition ('managed stock at or below a threshold'), so an agent knows this is a filtered product listing rather than an arbitrary query. It does not explicitly distinguish itself from the sibling list_products, leaving that inference to the name.

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 explicit when-to-use or when-not-to-use guidance, and the closest alternative, list_products, is never mentioned. The agent must infer that this is the narrow 'stock below threshold' variant of a product listing purely from the name and the filter phrase.

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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true; the description adds real value on top by disclosing that notes default to private, can optionally notify the customer, and are gated behind human approval rather than applied immediately. It does not discuss whether re-proposing the same note creates a duplicate proposal, which matters given idempotentHint=false.

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 action and followed by the approval constraint; every clause carries information and nothing is padded.

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 non-destructive proposal tool with no output schema, the description covers what is created, its visibility default, and the approval gate an agent must expect. It leaves open what the tool returns (a proposal identifier for later apply_proposal) and any note-length constraint, but those are minor against 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 coverage is 50%: only reason and customer_note carry schema descriptions. The description's '(private by default, or visible to the customer)' glosses the customer_note flag and its default, adding meaning beyond the terse 'true = the customer is notified', but order_id and note receive no explanation in either the schema or the description. That is adequate but not compensating for the coverage gap.

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 and resource ('Propose adding a note to an order') and scopes it with the private-vs-customer-visible distinction, which clearly separates it from sibling proposals such as propose_order_status or propose_refund. It stops short of explicitly naming those siblings, so differentiation is implied by the resource rather than stated.

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?

'Requires human approval' gives the agent the key workflow context: this tool stages a change rather than committing it, so a separate apply step follows. It does not mention the apply_proposal/list_proposals siblings by name or state when a note should not be proposed, so there are no 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 declare destructiveHint=true and openWorldHint=true, so mutation risk is covered. The description adds genuine context by stating the call only proposes and needs human approval (i.e., it does not apply immediately), but says nothing about transition validity, conflicts with existing proposals, or what happens on rejection.

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 action and followed by the approval constraint; no filler. The parenthetical example earns its place by clarifying the kind of change intended.

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 three-parameter mutation tool with no output schema and zero schema description coverage, the description is too thin. An agent still lacks the purpose of 'reason', the meaning of the status enum values, and any notion of what a returned proposal looks like or how to reference it later.

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 carry parameter meaning, and it largely does not. The example hints at the status field and the name implies order_id, but the required 'reason' parameter is never mentioned and the seven-value status enum is not explained.

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 ('Propose a new status for an order') and illustrates it with a concrete transition (on-hold → processing). It is clearly distinct from sibling propose_* tools by naming the resource (order status), but it never explicitly contrasts itself with apply_proposal or propose_refund.

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?

'Requires human approval' implies this is the right tool when a change must go through review rather than direct mutation, which is useful routing context. However, there is no explicit guidance on when to pick this over apply_proposal, or whether a separate approval step must already exist.

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 already declare a non-read-only, destructive, open-world mutation, so the description's main added value is the approval gate and the currency-string format with an example. That approval requirement is behavioral context the annotations cannot convey and is important since the agent must know the change is deferred, not immediate. It stops short of saying a pending proposal record is created or how it is later applied.

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, both load-bearing: the first defines the operation and the price format, the second gives the approval constraint. Front-loaded and free of 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 5-parameter destructive mutation with no output schema, the description covers format and the approval gate but omits what happens to prices that are not supplied, how variations are scoped, whether a proposal handle is returned for apply_proposal, and why reason is mandatory. Adequate to start a call, but an agent would still be guessing on several fields.

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 only 20%, so the schema does little; the description compensates for the two price parameters by specifying store-currency strings and an example format, plus the empty-string semantics carried in the schema. Nothing in the description explains product_id scope, what variation_id selects, or the reason field's role and 5-character minimum, leaving half the 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?

States a specific verb ("Propose") plus the exact resource ("new regular and/or sale price"), which cleanly distinguishes it from the other propose_* siblings such as propose_stock_update or propose_refund. It doesn't explicitly name apply_proposal as the counterpart, so sibling routing is implied rather than spelled out.

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?

"Requires human approval" signals the workflow constraint and implicitly tells the agent this is not a direct write, which is useful context. However, it never states when to use this versus apply_proposal or list_proposals, nor what the preconditions are (e.g. valid product/variation, non-empty reason).

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 destructiveHint=true and openWorldHint=true, which on their own would suggest immediate money movement. The description usefully corrects that impression by disclosing the deferred, human-gated execution model and the apply_proposal dependency, which is real value beyond the annotations. It does not cover what happens on rejection, whether the proposal can be edited, or what api_refund triggers downstream.

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 with no filler, and the core action is front-loaded before the safety caveat. Every clause carries information the agent needs.

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?

There is no output schema, so the description should say something about what a successful call returns (a proposal identifier?) and whether amount is validated against the order total. It covers the safety model well but leaves the parameter ambiguity and the return contract unaddressed, which is a meaningful gap for a five-parameter money-related 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 only 40% across five parameters, and the description adds nothing beyond the parenthetical '(partial)' hinting that amount may be below the order total. Most importantly, the two similarly named required string parameters, 'reason' and 'refund_reason', are left completely unexplained, so an agent has no way to know how they differ or what content belongs in each.

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 and resource ('Propose a (partial) refund on an order'), which separates it cleanly from read-oriented siblings like get_order and from the other propose_* tools by resource. It stops short of explicitly naming a contrasting sibling, but the resource name alone makes the choice 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?

Mentioning that money moves only after human approval and apply_proposal runs implicitly tells the agent this is step one of a two-phase workflow and names the follow-up tool. However, it never states when to prefer this over alternatives, whether a direct refund path exists, or what conditions make a refund appropriate, so the guidance is implied rather than explicit.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the mutation risk is declared. The description adds genuine value by clarifying that the call only creates a proposal pending human approval rather than writing stock immediately. It does not explain what happens to the current quantity, whether the value is absolute or a delta, or what the proposal record looks like.

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, front-loaded sentences with no filler; the core action comes first and the approval caveat second. 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?

For a four-parameter, human-gated mutation with no output schema and no documented parameters, the description leaves too much open. An agent cannot tell from it what a successful call returns (a proposal ID?), how the proposal is later applied, or what the mandatory reason is for.

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 carry parameter meaning and largely does not. "Product or variation" only loosely signals that variation_id is the optional fourth parameter; nothing explains product_id, the minimum-0 constraint on stock_quantity, or why a free-text reason of at least 5 characters is mandatory.

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 ("Propose") with a specific resource ("new stock quantity for a product or variation"), which separates it from siblings like propose_price_update or propose_refund. It does not explicitly name a sibling to contrast with, so it stops 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?

The clause "Requires human approval" implies this feeds a propose-then-apply workflow, which hints at when to use it rather than a direct stock mutation. However, it never names apply_proposal or list_proposals, nor does it state when NOT to use this tool (e.g., for read-only stock checks, use get_product).

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 openWorldHint=true, so safety is covered, and the description adds the aggregation nature of the result. However, it omits key behavior: what happens when no period is supplied (default window), whether date_min/date_max take precedence over period, and whether both custom-range bounds are required.

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

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

A single compact sentence with the metric list up front and the period options immediately after; nothing is redundant or padded.

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 3-parameter, no-output-schema tool, listing the returned metrics is helpful and covers the output gap. But it leaves the custom-range mechanics and default-period behavior undefined, which are the details an agent most needs to call it correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, but it only restates the period enum values already visible in the schema. The date_min/date_max parameters are never named or explained — 'custom date range' only hints at them without stating format, pairing, or precedence.

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 resource (aggregated totals of sales, orders, items, refunds and averages) scoped to a time period, which lets an agent distinguish it from sibling listing tools like list_orders or get_order. It does not explicitly contrast itself with those siblings, keeping it 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?

It enumerates the accepted period values but gives no explicit when-to-use guidance, no mention of when to prefer the detailed siblings (list_orders, search_customers) over this aggregate view, and no prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description does add real behavioral context beyond that: 'PII is masked by default' warns the agent that returned values are redacted, which affects how results should be presented. However, it never explains how to request unmasked data, what fields are considered PII, or how partial matching and pagination behave.

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 fragments, front-loaded and free of padding, so there is no wasted wording. But the terseness crosses into under-specification: neither sentence is a complete clause, and the PII note appears as an aside rather than an instruction. It is efficient without being self-sufficient.

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 3-parameter read-only lookup with no output schema, the safety profile is fully covered by annotations and the description supplies the two facts an agent most needs: what fields match and that results are masked. The remaining gap is pagination behavior and whether masking can be lifted, which are noticeable but not blocking for correct invocation.

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

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

Schema description coverage is 0% across 3 parameters, so the description carries the full burden and only partially meets it. Saying matches occur 'by email or name' gives real meaning to the required `search` parameter. It says nothing about `page` and `per_page`, leaving pagination semantics entirely undocumented in both the schema and the prose.

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 name is 'search_customers' and the description 'Registered customers by email or name' restates the resource while adding the one useful fact that matching works on email or name. It is a noun fragment with no verb, so the agent has to infer 'search/list' from the tool name rather than the prose. No sibling tool searches customers, so no differentiation is needed, which keeps this above a pure tautology.

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

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

There is no when-to-use guidance, no mention of what to do when no match is found, and no reference to any alternative tool among the many siblings. The only implicit guidance is the 'email or name' hint, which describes input shape rather than usage context. An agent must guess whether this reads live data or cached records.

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 openWorldHint=true, so the safety profile is covered. The description adds only that the payload covers name, URL, currency, platform versions, and active gateways, which is useful context but no detail on shape or reliability. With annotations carrying the bar, a 3 fits.

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 economical clause with no wasted words, and the key subject ('Store name, URL, currency...') is front-loaded. It is a fragment rather than a complete statement, which slightly weakens the lead.

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?

There is no output schema, so the description must convey what comes back, which it does at a field-list level. However, it never says the result is a single object or that these are configuration values, leaving the response shape ambiguous. For a zero-param read tool this is adequate but incomplete.

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 zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The listed fields are not inputs, so restating them does not constitute parameter 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 is a bare field list ('Store name, URL, currency, WooCommerce/WordPress versions and active payment gateways') with no verb, so it only implies retrieval. Given the name 'store_info' and the readOnlyHint, an agent can infer it reads store configuration, but nothing in the text explicitly says 'returns' or 'gets'. It is distinguishable from siblings only by subject matter.

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 when-to-use guidance, no mention of an alternative, and no precondition. The agent must infer that this is the entry point for store-level metadata rather than, say, sales_summary or list_products.

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