Expand polyarchy node

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

With no annotations, the description carries the transparency burden. It discloses the key behavioral trait that the tool does not update an open polyarchy canvas and returns the delta only to the caller. It also explains behavior per nodeType. It does not mention rate limits or auth, but for a fetch operation the critical side-effect nuance 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 four sentences, each earning its place. It front-loads the core purpose, then breaks down behavior by node type, and ends with the important side-effect note. It is information-dense without being verbose, and well-organized.

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 the tool's moderate complexity (6 params, no output schema, no annotations), the description covers the core behaviors and usage patterns. It explains the node types, dimensions, and the delta concept. It could mention output format or error cases, but for a fetch tool this is adequate.

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 67%, so the description compensates by explaining how parameters combine: 'For nodeType attribute pass attr+value to load the whole cohort' and 'Dimensions for a user node: org, groups, access, attributes.' This adds meaning to nodeType and dimension that the schema doesn't fully describe. However, it doesn't elaborate on every parameter, so not a 5.

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 starts with a specific verb+resource: 'Fetch one node's relationships from Microsoft Graph as a nodes/edges delta.' It clearly distinguishes itself from siblings by describing node types and dimensions, and explicitly notes it does not update a canvas, setting it apart from visualization tools.

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 clear context for when to use it: it explains that for group/role nodes it returns members, and for attribute nodes you pass attr+value. It also clarifies that the delta is returned to the caller only and doesn't update the canvas. However, it does not explicitly name alternative tools or state when not to use this tool.

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