node_inspect

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

Annotations already mark this as read-only and non-destructive. The description adds valuable non-annotated context: the swarm manager requirementency, the relevant fields (role, availability, status, manager reachability), and the dict return shape. It does not discuss authentication details, but those are less critical with the read-only annotation.

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 compact, front-loaded with the purpose, and every sentence adds signal: system requirement, payload summary, sibling guidance, argument meaning, and return type. No filler or tautology.

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 single-parameter inspect tool with no output schema, this description covers the prerequisite, how to identify the parameter value, what fields the result contains, and even handy sibling relationships. There is no missing information that would prevent an agent from invoking it 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 only says id_or_name is a string, but the description explains it accepts 'The node id or hostname (as shown by node_list).' That fully compensates for the 0% schema coverage by defining the parameter meaning and its source, though it stops short of showing an example or specifying short-ID syntax.

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 precise verb and object: 'Get a swarm node's full inspect payload by id or name.' It clarifies the resource, the lookup key, and what kind of payload is returned, distinguishing it from broader swarm or listing 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?

It gives an explicit prerequisite ('Must run against a swarm manager'), tells the agent to use node_list to discover nodes first, and points to service_ps as the alternative when the goal is to see what a service runs on a node. This is clear routing between sibling tools.

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