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

It adds substantive behavior beyond the annotations, notably that a node with no active rules accepts requests from any IP and origin. It also discloses the Global-node-only constraint and gives actionable troubleshooting for a 403 scenario. These are important operational traits that the annotations alone do not convey.

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 front-loaded with the core action and scope, then adds two short sentences covering default behavior and troubleshooting. Every sentence contributes useful information with no filler.

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 full schema description coverage, the read-only annotations, and the presence of an output schema, the description covers the remaining gaps well: node scope, default allow behavior, and escalation guidance. An agent has enough information to call this 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?

Schema description coverage is 100%, so node_id, status, and rule_type are already documented in the input schema. The description mentions IP and Origin rules and Global nodes, which adds mild semantic context, but it does not explain the status or rule_type filters beyond what the schema already provides.

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 gives a specific verb and resource: 'List a node's access rules.' It also adds the scope 'IP and Origin allowlists, Global nodes only,' which sharply distinguishes this read-only listing tool from sibling mutation tools such as create, update, delete, and set_node_access_rules_status.

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 usage context, including that the tool applies only to Global nodes and that a 403 despite correct configuration should be escalated via contact_chainstack. It does not explicitly contrast when to use this listing tool versus get_node or the mutation siblings, but the context is still clear.

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