expand_schema_node

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses the return shape, the meaning of different kind/view combinations, and even labels the role mapping as a 'heuristic role map,' showing honesty about the output. It does not explicitly state side effects (e.g., read-only), but the phrase 'return a delta to merge into the canvas' strongly implies a non-mutating, client-side integration.

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 dense yet front-loaded with the main purpose and then systematically covers each kind. There is minimal redundancy and every sentence conveys meaningful information. However, the dense block could be slightly more scannable with bullet points, and the long sentences require careful reading.

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 no output schema and no annotations, the description does a good job explaining the return shape and the many behavioral branches based on kind/view. It covers all major variants and mentions the caveat about heuristic role mapping. It does not handle edge cases or error conditions, but for a graph-expansion tool with five parameters, the core behavior is well covered.

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 high (80%), so the schema already documents parameters like 'since' and 'endpoint'. The tool description adds significant value by explaining how kind and view interact (e.g., EntityType + view='entity' returns schema neighborhood, while view='permission' returns permissions). This goes beyond the schema's enum names and helps an agent select parameter values appropriately.

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 a specific action ('Expand one node of the schema graph') and resource ('schema graph node'), and describes the exact return shape ('{nodes, edges, message} delta'). It also distinguishes itself from the sibling tool by calling itself 'the interactive companion to visualize_schema_graph' and by detailing kind-specific behavior for EntityType, Permission, and Role.

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 gives clear context by positioning the tool as an interactive companion to visualize_schema_graph, and explains when each kind/view combination is appropriate. However, it does not explicitly name alternatives or state when not to use this tool (e.g., when to prefer get_node_timeline or search_schema_objects), so it stops short of an explicit when/when-not distinction.

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