find_nodes

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

With no annotations, the description must disclose behavior on its own. It explicitly warns about the performance/result-size consequences of unfiltered searches, which is the main behavioral risk. It also implicitly suggests this is a read-only search operation. A more detailed mention of output format would raise this further, but the key behavioral trap is covered.

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 and efficiently structured: a one-sentence summary, a usage guideline with a warning, and a clear args list. The critical narrowing advice is front-loaded before parameter details alerting the agent to the main pitfall. No redundant or filler sentences.

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 four optional parameters and no output schema, the description covers all invocation requirements: filter semantics, scoping, and a warning about broad searches. It does not specify the return structure, but as a search tool that is presumed a list of nodes; this minor omission prevents a perfect score.

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 0%, so the description fully compensates. It explains each parameter in plain terms: pattern as a glob (with example 'box*'), node_type as a type filter (e.g., 'box', 'null'), context as a category filter (e.g., 'Sop'), and inside as the root path for scoping. This is far richer than the bare schema titles.

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 the specific verb 'Search' with a clear resource ('nodes') and explicit filter dimensions (name pattern, type, context). It clearly distinguishes itself from sibling search tools like find_error_nodes, find_expensive_nodes, and find_usd_prims by focusing on generic node discovery via structural filters.

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?

Provides concrete guidance: use 'inside' to scope searches, and supply at least one of three filters. It warns against unfiltered searches from '/' citing the risk of hundreds of results, giving the agent an implicit rule for safe invocation. It doesn't explicitly mention when to prefer alternative search tools, but the criteria are clear enough for correct use.

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