sd_list_node_definitions

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about pagination ('bounded page') and graph scoping ('in one graph'), which is useful operational behavior beyond the annotations. It doesn't disclose return format, but an output schema exists. No contradiction.

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?

Single sentence, 10 words, zero redundancy. It front-loads the action and scope, making it easy to process. No filler content.

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?

The tool has 4 parameters including a nested GraphRef, but the one-sentence description leaves terms like 'atomic definitions' unexplained and offers no guidance on query syntax or result structure. However, the output schema covers return values, and the description gives the essential purpose, making it minimally viable.

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 must compensate. It implicitly references the graph parameter ('in one graph'), search functionality ('Search'), and pagination ('bounded page'), but doesn't explicitly explain limit/offset/query semantics or the GraphRef structure. It provides partial meaning but not thorough parameter-level guidance.

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 verb 'Search' with the object 'a bounded page of atomic definitions' and scope 'in one graph', clearly indicating it lists/search definitions within a graph. It distinguishes from library-wide search tools but doesn't explicitly differentiate from sd_list_graph_nodes, which lists graph nodes, leaving 'atomic definitions' somewhat ambiguous.

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?

No usage guidance is provided. The description doesn't state when to prefer this over sd_list_graph_nodes or sd_search_library, nor mention any alternatives or exclusions. It's left to the agent to infer context from the name and basic description.

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