get_node_details

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

No annotations are provided, so the description fully takes on the responsibility. It discloses key behaviors: the tool makes a single API call, the return type changes based on whether a single node or all nodes are requested, the result is an empty dict if the node is not found, and errors occur for unsupported inputs like comma-separated lists. This is thorough for a read operation.

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 well-structured with clear headings (USAGE, FILTERING, etc.) and front-loaded with the purpose. It contains no fluff, but could be slightly more concise; for instance, the 'PREFERRED TOOL' statement could be integrated into the main text. Overall, every sentence adds value, but some repetition exists.

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 has 4 parameters, all optional, and an output schema exists (though not shown), the description covers all necessary aspects: usage, parameter explanations, edge cases (not-found, errors), return values, and examples. It is complete and leaves no ambiguity for the agent to use the tool correctly.

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?

The schema description coverage is 0%, meaning the description must fully explain each parameter. It does so effectively: node_id (None for all, single string, no lists), fields (comma-separated), name (substring match on user-visible name), type_ (substring match on device type). The description adds critical usage context and examples that go far beyond the schema's type definitions.

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 explicitly states this is the 'PREFERRED TOOL for getting comprehensive node information efficiently', highlighting that it retrieves config, status, and params in a single API call. It clearly distinguishes itself from sibling tools like get_node_status and get_params by offering combined data efficiently.

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 guidance on when to use the tool (when comprehensive data is needed efficiently) and when not to (e.g., avoid comma-separated node IDs; instead use filtering with node_id=None). It explains the default behavior for node_id and offers examples. However, it does not explicitly compare with sibling tools like get_node_status or get_params for specific use cases.

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