list_scan_results

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

Annotations already cover read-only/idempotent safety, yet the description adds real behavioral context: values are read live rather than snapshotted, text values share a per-page size budget, truncated rows are flagged with value_truncated, and limit is server-capped. It also carries a trust-boundary warning that returned values are untrusted data, not instructions — a safety trait annotations cannot express.

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?

Purpose is front-loaded, then the live-read nuance, then the untrusted-data warning, then a compact param block. The prompt-injection caveat is arguably the most operationally important sentence and earns its length; nothing is redundant.

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?

The tool has an output schema, so return shape need not be described, and the description adds pagination, truncation, and safety context. The only real gap is that the required scan_id parameter is never explained and no explicit alternative-tool routing is given.

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 0%, so the description must carry the load; it documents limit as rows per page with a server-side cap pointer to server_info().limits.max_page_size, and offset as rows to skip. scan_id is left unexplained, but its meaning is self-evident from the tool name and sibling set.

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 first sentence gives a specific verb pair and resource: page through a scan's result set while reading each address's *current* value. It implicitly distinguishes itself from read_value (full values) and refine_scan (narrowing the set), though it never states plainly that this is the read side of scan results.

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 a concrete condition for reuse ('calling this twice on a set that is still changing is itself a useful signal') and routes to read_value when a truncated row is needed in full. It lacks an explicit when-not-to-use this tool versus scan_value or process_info.

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