Get TouchDesigner info

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond that: it succeeds with connected:false when TD is offline, reports a reason, and warns about bridge version mismatches. These are behavioral traits not inferable from annotations alone, making the description highly transparent.

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 three concise sentences, front-loaded with the core purpose. Every sentence provides value: what it does, what it returns, when to use it, and an edge-case warning. No filler or repetition, achieving high information density without verbosity.

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?

For a tool with no parameters and no output schema, the description fully covers the essential context a caller needs: return fields, offline behavior, and the stale-bridge gotcha with a pointer to the corrective tool. It is complete for its simplicity and leaves no major operational ambiguity.

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 tool takes zero parameters, so the schema is trivially complete with no description needed for parameter syntax. The description implicitly confirms this by focusing entirely on output. Following the baseline for 0 params (4), this is appropriate even though no param-level detail is added.

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 clearly states the tool is a 'Read-only health check + TouchDesigner server info' with a specific verb and resource. It lists the exact return fields and explicitly says 'changes nothing', distinguishing it from mutation tools. It also differentiates itself by advising 'Use this first', setting it apart from diagnostic siblings like get_td_performance or get_bridge_logs.

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?

Explicitly instructs to 'Use this first to confirm the bridge is reachable', providing clear when-to-use guidance. It also explains behavior when TD is offline and warns about a stale bridge, pointing to reload_bridge as the alternative/fix. This gives the agent actionable decision logic without ambiguity.

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