check_magnet_design

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

With no annotations, the description carries the full burden and largely falls short: it never states whether the check mutates anything, what inputs it requires to be meaningful, or what a result looks like. The tier breakdown ('Free: Warnings · Pro: Sizing and fit · Business: + Per-machine fit, validation tests and QC plans') is genuine behavioral disclosure about how much answer you get back, which is worth some credit, but it is framed as a sales ladder rather than operational 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 useful content is one front-loaded sentence; everything after it is pricing/upgrade marketing with a tracking URL. That material partly serves a purpose (tier-gated output depth) but is verbose and repeated in link form, and it crowds out information an agent actually needs to invoke the tool.

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?

Thirteen parameters, no annotations, no output schema, and the description explains neither the failure modes it detects nor the shape of the warnings it returns. For a tool of this input complexity, the description leaves the agent guessing about what a call produces and how to interpret a 'warning'.

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 85%, so per the baseline the schema is nominally responsible for the 13 parameters — though most of those descriptions are just 'Default: ""' stubs. The description contributes nothing explicit about use_case, load_mode, environment, child_accessible, or max_temp_c, only indirectly implying concerns like child safety and hardware fit through the tier copy.

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 gives a specific verb and resource — checking a proposed printed magnet design for hidden failure modes — which is far more informative than the name alone. It does not, however, distinguish this from nearby siblings such as recommend_magnet_for_product, generate_magnet_qc_plan, or review_magnet_supplier_packet, so an agent cannot tell which of those to pick from this text.

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?

There is no statement of when to use this versus alternatives, no prerequisites (e.g. must a design or magnet spec already exist?), and no exclusions. The only conditional content is commercial tier gating, which describes output depth, not invocation guidance.

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