RealMarket Survey Builder

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the 15-question cap with possible omission of complete blocks, English-only source with in-conversation translation, the pricing prerequisite on currency and product_unit, and that calls are logged. The only soft spot is 'Missing images do not block drafting', which references no parameter in the schema and reads as residue from another 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?

The definition is front-loaded with the use case, then output shape, then language, then prerequisites, then exclusions — a sensible ordering with almost no filler. A couple of clauses are compressed to the point of being cryptic ('Missing images do not block drafting'), which costs a little clarity without adding bulk.

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 an 8-parameter tool with 5 required fields, an output schema, and full annotation coverage, the description covers the remaining agent-facing questions: output volume, block structure, language handling, the pricing prerequisite, and the boundary against recruitment or messaging use. Nothing needed to invoke 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. The description still adds cross-parameter meaning the schema only states per-field: 'Pricing requires currency and product_unit' ties two optional parameters to one objective, and 'Same audience restrictions apply as for the primary objective' explains how extra_topics interacts with audience selection.

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 specific resource (a consumer questionnaire) and enumerates the exact scope it covers: packaging, concepts, pricing, repeat purchase, purchase frequency, non-buyers, brand perception. Combined with 'Returns up to 15 questions in complete blocks with screening, answer formats, purposes and fieldwork notes', an agent knows precisely what the tool produces without opening the 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 via the objective list, and explicit when-not-to-use follows: 'Do not use for recruitment, response collection, messaging or unrelated requests.' No sibling tools exist, so no alternative routing is needed; the exclusions do the routing work instead.

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