nodes.search

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

With no annotations provided, the description carries full burden and does well by disclosing: 1) returns ALL matches with confidence scores, 2) content search limitations by node type (sheet: headers+100 rows, code: 1000 chars, etc.), 3) performance consideration for large sheets (>1000 rows skipped by default), and 4) that AI should decide relevance. It lacks details about error conditions or authentication requirements.

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 efficiently structured with purpose statement first, followed by use cases, content search details, and performance considerations. Every sentence adds value - no redundant information. The bullet-point format for use cases and content types improves readability without wasting space.

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 search tool with 5 parameters and no output schema, the description provides excellent context about what gets searched, performance considerations, and return format (matches with confidence scores). It lacks details about the exact structure of returned results and any error scenarios, but covers most essential information an agent would need to use this tool effectively.

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 baseline is 3. The description adds significant value by explaining: 1) natural language support for query parameter, 2) practical implications of includeLargeSheets (performance trade-off), and 3) context about what 'searchContent' actually searches (content limitations by type). However, it doesn't explain the 'types' parameter's valid values or 'limit' parameter's practical constraints.

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 searches workflow nodes by name or content and returns matches with confidence scores. It distinguishes itself from siblings like nodes.getByName (specific lookup) and nodes.list (no search) by emphasizing broad search functionality across multiple node types with relevance scoring.

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 explicit usage examples ('the validation node', 'sheet with customer data', 'authentication code') and clear guidance on when to use includeLargeSheets parameter. It implicitly distinguishes from other search tools like layout.search by focusing on node content rather than layout elements.

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