add_helper

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the agent knows this mutates state without being destructive. The description adds the useful framing that these helpers are temporary visual aids and not part of production code, which reinforces the non-destructive nature. It does not disclose how helpers persist, when they are cleared, or that calling again stacks new helpers (relevant given idempotentHint=false).

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?

Two sentences, front-loaded with the debug-visual tag and the core action, then the helper catalogue. It is efficient with no filler, though the type list partially duplicates the schema enum and could be trimmed.

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?

With 9 well-documented optional parameters, full schema coverage, safety annotations, and no output schema expected, the description supplies what is needed to call it correctly. The main missing piece is how created helpers are managed or removed (the remove_helper sibling), but overall the definition is sufficient for correct invocation.

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 the schema already documents all nine parameters including defaults and the type enum. The description enumerates the helper types (box, axes, skeleton, arrow, grid, camera frustum, light helpers, plane) but this largely restates the enum rather than adding new syntax or format meaning. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

Specific verb plus resource ("Add a debug helper") and it enumerates the helper kinds, so an agent immediately knows what it creates. The "[DEBUG VISUAL]" prefix and "Nothing to put in code" note cleanly scope it as a dev-only visual tool. It does not name its natural counterpart remove_helper, so sibling differentiation is present but not explicit.

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?

"[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code." gives implied context that this is for debug inspection only, which is useful guidance. However there is no explicit when-to-use, when-not-to-use, or pointer to remove_helper for cleanup, leaving the practical usage workflow to inference.

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