Find TouchDesigner parameters

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds critical behavioral details: values are point-in-time snapshots, likely secrets are redacted and cannot satisfy filters, and the scan_truncated/count_complete fields must be inspected for completeness. It also states the prerequisite of the current structured bridge route and that it never falls back to raw Python or a full dump. This substantially enriches the agent's understanding.

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 compact, front-loaded with 'Read-only' and a clear purpose, and every sentence adds value—covering scope, constraints, limitations, and usage tips. No redundant or repetitive content is present.

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 tool's complexity (17 parameters, live system interaction, output schema present), the description covers all key aspects: what it searches for, the bounded/read-only nature, point-in-time semantics, redaction, completeness checks, prerequisites, and the guarantee of not falling back to raw Python. The output schema handles return-value details, so the description is sufficiently complete for effective use.

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 53%, so the description is not fully responsible for parameter semantics. The description summarizes the searchable dimensions (node, type/family, parameter name, value, expression, mode, non-default state) which maps to several parameters, but it does not clarify the semantics of parameters like time_budget_ms, node_scan_limit, parameter_scan_limit, limit, or type_match. These remain only partially understood from names and defaults, so the description only partially compensates for the coverage gap.

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 uses a specific verb ('search') and resource ('live TouchDesigner parameters'), and enumerates the filter dimensions ('node, operator type/family, parameter name, evaluated value, expression, mode, or non-default state'). It clearly differentiates from siblings like get_td_node_parameters by framing it as a bounded search rather than a full listing, and explicitly states it never falls back to raw Python or a full parameter dump.

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 context: it is a read-only, bounded search for live parameters, and advises to inspect scan_truncated and count_complete before claiming project-wide completeness. It implicitly discourages using raw Python or full parameter dumps, but it does not explicitly name alternative tools like get_td_node_parameters or specify 'use this when you need to search by criteria rather than list all.'

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