shelfrelay preview

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

Annotations are supplemented with details the schema cannot express: data transits through RapidAPI to a NAS service, consumes plan allowance, exactly one request with no automatic retries, originals preserved and verified results written as new local files, plus a prompt-injection warning that returned artifacts are untrusted. These are consistent with openWorldHint=true, idempotentHint=false, and destructiveHint=false. The cost and no-retry disclosures are exactly what an agent needs before committing a paid mutation-adjacent call.

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?

Front-loaded with purpose and return value, then constraints, then the trust warning. Almost every clause carries load-bearing information (cost, retries, preservation). It is long for one paragraph and could be trimmed slightly, but nothing is padding.

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 but high-consequence remote call with no output schema, the description covers consent, network path, billing, retry behavior, on-disk persistence, and output trust level. What is missing is a sense of the artifact's shape (how many updates, how to validate success vs partial failure) and any size limits on the request beyond the schema's 4096-char string bound.

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%; the consent parameter is fully documented in the schema and reinforced by 'Requires consent:true'. The description adds useful content hints for 'file' (it carries the records/policy envelope and optional previous_xml state) and that it is a local file, but never states whether the value is a path or inline JSON, which is the one ambiguity an agent must resolve to call this correctly. Baseline 3 for partial coverage.

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

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

The description names a concrete input (a local JSON request carrying the ShelfRelay records/policy envelope plus optional previous_xml state) and a concrete output (a review artifact with typed ONIX updates scoped to the physical-ISBN/single-authority profile). That is far more specific than the bare name 'preview' and separates it from the batch/optimize siblings. It stops short of explicitly contrasting with a named sibling, so 4 rather than 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?

'Requires consent:true' and 'Does not apply changes to WooCommerce or fetch referenced covers' set a clear boundary for when this tool applies and what it will not do. The preview-then-apply framing is implied by 'review artifact'. Missing: an explicit pointer to which sibling or follow-up call performs the apply step.

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