get_math_state

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

With no annotations present, the description carries the full burden and handles it thoroughly. It explicitly says the operation is read-only, never changes the display, costs a few queries per trace, and discloses operator-dependent response behavior including FFT peak handling and warnings.

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 description is front-loaded with the core purpose, then uses short paragraphs to cover the optional parameter behavior, operator-dependent keys, and side-effect/cost notes. Each sentence adds necessary information that is not already in the schema or annotations.

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?

Given the absence of an output schema, the description is unusually complete: it documents return shapes for both parameter modes, key selection per operator, FFT peak details and warnings, and the cost profile. Nothing an agent needs to call the tool correctly appears to be 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?

The schema provides only the type and default for channel, with zero property descriptions. The description compensates fully by stating the valid channel range (1-4), the flattened single-trace result shape, the all-traces result shape when omitted, and how traces are keyed by string numbers.

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 opens with a specific verb and resource ('Return the math trace settings') and enumerates the exact scope (channel, display, operator, sources). This is distinct from generic sibling getters like get_state or get_channel, so an agent can identify the tool's purpose immediately.

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 provides clear invocation context by explaining both the channel-given and channel-omitted cases, effectively telling an agent how to request a single trace versus all traces. It does not explicitly name an alternative getter or state when not to use this tool, so it stops short of full alternative routing.

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