Generate test data

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

No annotations exist, so the description carries the full behavioral burden and does so richly: free with rate limits (500 rows/50 columns per call), determinism guarantee ('same schema and seed give byte-identical output for the same generator version'), the x-generator-version header, and the output_path threshold for large results. The data-provenance constraint ('Send schemas only, never real data') is exactly the kind of safety context an agent cannot get from the schema.

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-loads purpose and the primary usage directive, then layers determinism, safety and output guidance. Dense but nearly every sentence carries a non-obvious fact; only the closing curl/sha256 sentence feels like it could be trimmed since it describes result shape.

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?

A 9-parameter tool with nested objects, no annotations and no output schema — the description compensates on every front: safety profile, rate limits, determinism, file-vs-return behavior, and even the shape of the result (sha256 + regenerating curl). An agent has everything needed to call it correctly on the first attempt.

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 baseline is 3. The description still adds meaning: it explains when to prefer schema over columns (Pydantic/Zod export, OpenAPI component), notes unmappable fields are named, and gives the practical threshold for output_path ('more than about 50 rows'). It stops short of explaining the chaos object or the columns type vocabulary, which stays in the 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?

States a specific verb+resource with output formats ('Generate realistic fake test data (CSV, JSON or SQL INSERTs) from a table schema'). It differentiates from siblings by name — list_column_types for type options, invalid_values and the sandbox_* tools for downstream steps — so an agent can route without opening schemas.

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 ('Use it first, when you need rows for fixtures, seed data or tests') plus a named sequencing of alternatives: list_column_types for options, then invalid_values, then sandbox_create/sandbox_payments. Also gives an alternative input mode (schema instead of columns), leaving nothing to inference.

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