Show the problem in 3D

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

Annotations declare readOnly/idempotent/non-destructive, and the description still adds substantial context beyond them: that no optimizer runs, that behavior depends on the client (MCP Apps card vs. text-only fallback with just region counts and estimate), the interaction contract for the 'Start the run' button, and the concrete error shape {"ok": false, "error": ...}.

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 opening and closing sentences are front-loaded and efficient, and the key constraint (no optimizer run) lands early. However, the middle block describing the three host modes for the 'Start the run' button is long, chatty, and largely about UI plumbing rather than helping an agent decide to call the tool or how to invoke it.

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?

There is no output schema, so the description must cover returns; it does by describing the card contents, the text-only fallback (region counts and estimate), and the error object. It omits whether the card is returned as part of the tool result payload versus rendered side-effect only, which is a minor gap for an interactive-render tool.

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?

With schema description coverage at 0%, the description carries the burden and does so: it names yaml_path and clarifies that 'the problem YAML' is expected and that 'relative paths start at the work folder', which the bare string schema does not convey. It does not specify the file extension or an example path, which keeps it from a 5.

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 first sentence states a specific verb and resource ('Show a problem YAML ... as a 3D view in the chat') and enumerates exactly what the view contains: design space, fixed/keep-out/solid/load regions, load-case arrows, and time/memory estimate. It explicitly distinguishes itself from check_problem ('the same checks as check_problem, in the same time') and from run_topopt ('No optimizer run').

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?

'Use it when the YAML is ready, so that the user sees the setup before the run' gives a clear trigger condition. It also routes the agent to the sibling alternative for the full facts and warnings ('The full facts and the warnings are in check_problem'). No explicit when-not-to-use case is stated, keeping it below a 5.

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