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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial detail beyond them: the 200 shape `{valid:true, warnings}`, the 400 with exact bad field path, that warnings are a solve-free approximation, and that the engine verdict — including `engine: "max"` and 503s — matches the optimize path exactly. That equivalence guarantee is the kind of context nothing else in the structured data conveys.

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 information is front-loaded correctly, but the 'free / no key / no quota / no solve' message is restated at least three times across the text, and the simulated-response sentence largely duplicates what the output schema already defines. Roughly a third of the description could be cut without losing meaning.

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?

Behaviorally this is close to complete: response codes, warning semantics, and parity with the optimize path are all explained, and an output schema exists so return values needn't be detailed. The gap is parameter documentation — for a six-parameter tool with a deeply nested body at 0% schema coverage, deferring entirely to another tool leaves the agent reliant on a sibling.

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 0% across a deep nested schema (parts, stock, options, matchedSets), so the description carries the burden — but it only says "same arguments as optimize_2d (field descriptions there)", deferring rather than explaining. The only parameter-level insight offered is that `engine` values, including "max", are validated identically, which covers a fraction of the surface.

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 and resource — schema-validates the same body `/v1/optimize/2d` accepts, without solving it — and explicitly distinguishes itself from the sibling optimize_2d by saying it does not spend a call. An agent can tell exactly what this does versus the optimize tools without opening a 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?

Gives a concrete when-to-use: validate payloads during integration, before you even have a key. It also implicitly separates itself from optimize_2d (this one does not solve), and points to optimize_2d for field descriptions. Missing is an explicit statement of when NOT to use it (e.g., when you actually need a cut plan).

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