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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: Regent performs policy checks and injects the credential so 'the key never reaches the agent,' which is meaningful auth-flow context. It stops short of describing rate limits, error behavior, or policy-denial handling.

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?

Three short sentences, front-loaded with what the tool reads and the allowed methods, with zero filler. Every sentence carries distinct information (endpoint, credential handling, safety assurance).

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 wrapper with full annotation coverage and no output schema, this explains the endpoint, method restrictions, and credential model adequately. Slightly incomplete on what a response or a policy rejection looks like, but nothing critical for correct invocation is missing.

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 80%, so the schema largely documents path, facts, intent, method, and user_token. The description only reinforces the method enum restriction (GET, HEAD, OPTIONS) and adds nothing about fact shape or token usage, so baseline 3 applies.

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?

States a specific verb and resource ('Read from http://demo-counterparty-api:8000 through Regent'), constrained to GET/HEAD/OPTIONS. The closing line 'Nothing is changed and no money moves' implicitly contrasts it with its write sibling, though counterparty_check is never named outright.

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 method constraint and read-only framing imply when this tool is appropriate, and the 'nothing changed' line hints the write variant exists. However, it never explicitly says when to call this versus counterparty_check, so selection still requires inference.

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