Ripey

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the link opens the store with the product pre-selected, and the product must already be published — which explains why a call might fail.

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

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

Two sentences, zero waste, with the core return value front-loaded and the prerequisite/provenance note following. Nothing redundant.

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, two-parameter tool with a 100% documented schema and no output schema, the description covers input provenance, preconditions, and the shape of the return value (a link). No significant gaps remain.

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 both parameters are fully documented in the schema, establishing a baseline of 3. The description restates the agent_key provenance already present in the schema and adds only the implicit constraint that product_id must refer to a published product.

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+resource: it returns a purchase link for a published product, and clarifies what the link does when opened (store with product selected). This is clearly distinguishable from sibling read tools like list_products or sales_summary, though no sibling is named explicitly as a contrast.

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?

States the prerequisite that the product must be published and tells the agent where the required agent_key comes from (open_store), which implicitly routes the agent through the correct preceding tool. No explicit when-not or alternative tool is named, but the usage context 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 declare non-readOnly, non-destructive, non-idempotent, but the description adds the important behavioral fact that the created entity is unpublished and that a human approval step must precede going live. It does not mention whether repeated calls create duplicate drafts or what permissions the agent_key grants, so it falls short of fully rich 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 short sentences with the non-live guarantee front-loaded and the approval workflow immediately after; there is no filler and the sequencing is easy to scan.

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

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

For a creation tool with no output schema, the description covers scope, prerequisites and next steps, but never indicates what is returned (e.g. the product identifier needed for the publish call). That is the one piece an agent needs to chain to the next 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 coverage is 100%, so all six parameters including the type enum and price bounds are already documented in the schema. The description only restates the provenance of agent_key (returned by open_store), which the schema already says, so baseline 3 applies.

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

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

"Create a DRAFT product in the store" pairs a specific verb with a specific resource and immediately narrows scope (draft only, nothing live). The contrast with the publish sibling makes the boundary between the two tools explicit without needing to open 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?

It names the exact follow-up sequence: show the user the draft fields, get approval, then call publish. It also states the prerequisite that agent_key comes from open_store. Both when-to-use and the gating condition are explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds useful behavior — it enumerates the returned fields and constrains status to draft or published. It omits ordering, pagination, or result-size behavior, which is the main remaining gap.

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, zero filler, with the core listing behavior front-loaded and the prerequisite second. 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?

With no output schema, the description usefully compensates by naming the returned fields and status values. For a one-parameter read tool this is nearly complete; only pagination/ordering expectations are 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 coverage is 100% and the single agent_key parameter is fully documented in the schema, including the rpy_ prefix hint. The description restates the same provenance fact rather than adding new syntax or format detail, so baseline 3 applies.

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

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

Specific verb + resource ('List the store's products') plus the fields returned (id, price, status) and the status domain. It is clearly distinguishable from create_product and publish by the read-only listing verb, though it never names a sibling 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?

Gives the prerequisite for calling it: pass the store's agent_key, which is obtained from open_store — a concrete dependency an agent must satisfy first. It stops short of stating when to prefer this over siblings like sales_summary or publish, so no exclusions are covered.

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?

Despite having no output schema, the description discloses the return payload (store URL, private dashboard link, agent_key) and its downstream use. It also adds security-critical context not in the annotations: the wallet must be a public address, never a secret key, and test mode substitutes a demo address when omitted.

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 sentences, each doing distinct work: purpose, prerequisites, and parameters plus returns. The purpose is front-loaded and nothing is repeated from the name or title.

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-idempotent, open-world creation tool with no output schema, the description covers purpose, prerequisites, return values and the credential hand-off. It omits what happens on failure or on repeated invocation (the annotation flags idempotentHint=false but the description never warns that re-calling creates another store).

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 genuinely adds meaning: it clarifies that wallet is optional, constrains it to a public address with an explicit prohibition on secret keys, and explains the test-mode fallback. It does not add format/syntax hints beyond the schema's example.

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 opening sentence states a specific verb and resource ('Open a new Ripey store') and the closing sentence establishes its role as the onboarding/credential-minting step for the other Ripey tools. That makes it trivially distinguishable from siblings like create_product or sales_summary, which operate inside an existing store.

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?

'Ask for the store name and the user's email first' and 'pass it to the other Ripey tools on this same connection' give explicit preconditions and a clear hand-off to the siblings. It stops short of stating when NOT to call it (e.g. what to do if the user already has a store), so it is not a full 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 cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), so the description only needs to add context — and it does, by revealing the real-world effect that the draft becomes purchasable by buyers. It stops short of saying whether publishing can be undone or how to revert, which would be valuable for an open-world mutation.

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 short sentences, front-loaded with the action and its effect, then the gating rule, then the credential hint. Nothing is padded or redundant.

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 mutation with no output schema, the description covers action, precondition, and parameter sourcing. It would be stronger if it indicated what the agent gets back or whether the draft ID remains valid after publishing.

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% and both parameters are fully documented in the schema, so the description's mention of agent_key duplicates rather than extends it. Baseline 3 applies; no additional semantics (format, validation, failure modes) are contributed.

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?

A specific verb and resource ('Put an approved draft on the store') with the business consequence spelled out ('so buyers can purchase it'). This distinguishes it cleanly from siblings like create_product (which makes the draft) and open_store (which supplies the key).

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?

'Only call this after the user approves the draft' is an explicit, actionable precondition that tells the agent when to invoke it and implicitly when not to. No alternative tool is named, but none exists in this sibling set, so the gap is minor.

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=false, so safety is covered. The description adds real value beyond them by disclosing the default lookback window and the contents of the result, which matters because there is no output schema to explain the return values.

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 filler. The core purpose and returned metrics are front-loaded, and the prerequisite note follows the main clause in a logical order.

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 purpose, returned fields, default window and the prerequisite for the one required parameter. Nothing an agent needs to call it 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 coverage is 100%, so the baseline is 3, but the description adds the default value (7 days) that the schema does not state, and reiterates the agent_key provenance. That is genuine added meaning beyond the parameter definitions.

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 ('Summarize') and resource ('the store's sales') and enumerates the returned metrics (revenue, orders, customers, top products). It is clearly distinct from the sibling tools (product CRUD, checkout, publish) even without naming them 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?

It states the prerequisite explicitly: pass the agent_key returned by open_store, which tells an agent what must happen first. It also gives the default window (7 days). It does not name a when-not condition or an alternative, 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.