simplify

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

With no annotations provided, the description carries the full burden—and it delivers. It discloses that the tool writes to disk and returns the path, that `config` causes a pre-processing pipeline (filter + overlay + prune), and that the result is 'a faithful subset.' It does not mention side effects like overwriting existing files or how the random count is seeded, so it's not a perfect 5, but the main behavioral surface is well covered.

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 core action is front-loaded in the first two sentences, followed by a compact bulleted list for the optional-property parameter modes. Every sentence adds information—there is no filler or restatement of the input schema. The structure makes the trickiest parameter semantics scannable.

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 tool with six parameters and no output schema, this description covers the input source, the transformation behavior, the output destination fallback, the full parameter-mode matrix, and the `config` pipeline. The only minor omissions (overwrite behavior, exact return-value shape) are understandable given the description text and the 100% schema coverage; nothing an agent needs 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 already 100%, so the baseline is 3; the description adds genuine value on top by explaining the semantics of `optional` modes (keep all vs. exactly N vs. random range), the mutual exclusivity of `optional` with `optional_min`/`optional_max`, and the `config` preprocessing pipeline. It loses one point because `output`'s fallback behavior is stated but the random-range semantics could have been slightly clearer about the inclusive/exclusive bounds.

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 states a specific verb (simplify) and resource (OpenAPI spec), enumerates exactly what transformation is applied (drop/reduce anyOf/oneOf, strip x-* extensions, limit optional properties), and distinguishes its output use case from siblings by naming `serve_locally`. This is clearly differentiated from sibling tools like `lint`, `pack`, and `serve_locally`.

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 this tool ('when a spec is too large or too complex to mock cleanly') and names the downstream sibling (`serve_locally`) that should receive the output. It also includes detailed mode-selection guidance for the optional-property parameters (omit, exact N, or min/max range), which routes the agent to the correct parameter combination and even notes the mutual-exclusion requirement.

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