node_inspect

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing the manager requirement ('Must run against a swarm manager') and detailing the information returned ('Shows role, availability, status, and manager reachability' and 'returns: dict - The node's attrs'). This goes beyond the annotations without contradicting them.

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: a one-sentence summary, a prerequisite/alternatives sentence, and explicit args/returns sections. It is slightly verbose due to the multiple alternatives in one long sentence, but every part contributes useful context. No redundant information.

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?

For a simple read-only tool with one parameter and no output schema, the description is fairly complete: it covers purpose, prerequisite, parameter meaning, return structure, and related tools. It does not discuss error handling or authentication, but those are less critical given the annotations and the straightforward nature of an inspect operation. It ranks above average for completeness.

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 input schema has no description for the only parameter (schema coverage 0%), so the description must compensate. It does so effectively: 'args: id_or_name - The node id or hostname (as shown by node_list).' This clarifies the accepted values and provides a reference for obtaining them. The description adds sufficient meaning beyond the bare type 'string'.

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 opens with a specific verb and resource: 'Get a swarm node's full inspect payload by id or name.' This clearly distinguishes it from sibling tools like node_list (which enumerates nodes) and node_update (which modifies nodes). The mention of 'full inspect payload' further differentiates it from other inspect tools by specifying the swarm node scope.

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 explicitly states a prerequisite: 'Must run against a swarm manager.' It also provides alternatives: 'use node_list to enumerate nodes first, or the docker://nodes resource for a fleet summary; service_ps(filters={"node": ...}) shows what a service runs on one node.' This gives clear guidance on when to use this tool versus related tools, satisfying the 'when vs alternatives' requirement.

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