search_node_docs

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

Annotations already declare read-only, so the extra value here is real: it discloses truncation behavior (overflow hits appear by name in otherMatches), per-query limit semantics in batch mode, and that scope "raw" bypasses structured search to grep bundled files including client graphs and enum members. It does not say what happens if neither query nor queries is supplied, which is the main remaining behavioral gap.

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?

Purpose is front-loaded, but the body is one dense run-on paragraph mixing search syntax, wildcard behavior, raw scope, batch mode and editorial asides ('the slowest part of writing a graph in a blind test', 'three or four is enough'). The content is mostly useful; the packaging would benefit from line breaks or short labeled clauses.

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?

With no output schema, the description does the job of describing returns: hit shape, bilingual content, otherMatches overflow, and per-query results in batch mode. Only the empty-argument behavior and the relationship to sibling knowledge tools are left unstated.

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 coverage is 0%, so the prose must carry all four parameters, and it largely does: limit's role via otherMatches and per-query counting, scope 'server' vs 'raw', queries as up to 30 batched searches. It never names the parameters explicitly or explains the optional-both case, so mapping prose to field names takes a small inference step.

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?

States a specific verb and resource — search the node graph API docs — and describes exactly what a hit contains (method/event signature, behavior, per-parameter meaning, bilingual). It is clear about its domain, but never names the sibling search_knowledge/read_knowledge tools, so an agent must infer which search to reach for.

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?

Gives concrete usage advice: query "*" to enumerate everything, scope "raw" for grepping bundled definition files, and queries[] batching for levels needing 30-40 nodes with 'three or four is enough' per query. No exclusions or when-not-to-use guidance relative to the sibling knowledge-search tools.

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