get_nodes

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

With no annotations, the description carries the full burden. It discloses that the tool inspects static properties and that listing is capped (with paging via offset), which covers the key behavior. However, it does not mention potential errors (e.g., invalid networkId) or explicitly state it is read-only (though 'inspect' implies it). It also doesn't describe the response format, but that is less critical. Moderate coverage.

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 two sentences, with the core purpose front-loaded. Every sentence adds value: the first defines the scope, the second provides usage guidance. Zero waste and easy to scan.

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 read-only inspection tool with three parameters fully documented in the schema, the description covers the essential operational aspects: the scope of properties, the 250-item cap, and paging via offset. It does not elaborate on response structure, but that is not critical given the simple nature. Minor omission: no mention of error cases, but overall it is complete enough for safe invocation.

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 100%, so the description adds minimal new meaning. It reinforces the purpose of nodeIds ('keep the response small') and clarifies the cap, but the schema already documents all parameters. The description does not introduce new syntactic details, so it meets the baseline for high coverage.

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 uses a specific verb 'inspect' and clearly names the resource 'network nodes', listing the properties per node type (junctions, reservoirs, tanks). This distinguishes it from sibling tools like get_node_results (dynamic results) and get_links, making its purpose unambiguous.

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 tells the agent when to pass nodeIds (to keep response small) vs omit (to get a capped listing), giving clear conditional usage. It does not explicitly name alternatives or exclusions, but the context of being a read-only inspection tool is clear. The guidance is sufficient for basic selection.

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