Preview Product

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds a precise error contract: 'on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ...}'. It also commits to never returning full text and states that retrying after correcting input is always safe. This is valuable behavioral context not present in annotations.

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

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

The description is more verbose than strictly necessary but every section earns its place: purpose, example shape, constraint, usage guidance, error behavior, and retry safety. The 'FREE.' fragment adds little value and slightly distracts, but the overall structure is front-loaded and logically organized.

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 single-parameter read-only tool, this description is complete: it explains what it returns, what it never returns, how errors behave, and which sibling tools cover the excluded cases. The output schema and the inline example round out the return contract. No critical context 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 schema already provides 100% coverage with a clear slug description ('Product slug exactly as returned by search_catalog or recommend_products, e.g. "inbox-zero-assistant"'). The description reinforces this with a typical input example but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Preview one product: metadata, persona teaser, and paid-skill teasers.' It clearly distinguishes itself from full-content tools by stating 'Returns teasers only, never full text.' This is unambiguous and uniquely identifies the tool's role.

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

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

The description explicitly says when to use it ('Use to judge a product before committing') and when not to ('Not for the complete persona or skill bodies (get_full_persona, get_full_product), and not when the caller wants instructions they can act on now (get_free_skill)'). It names the exact sibling alternatives, leaving no inference required.

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