koios_address_list

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'first appearance on the blockchain' which is a useful behavioral detail, but it does not disclose pagination behavior, ordering defaults, or the potentially large result set. The tool's read-only nature is implied but not explicitly stated, and there is no mention of rate limits or response format. This provides minimal transparency beyond the core operation.

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 a single concise sentence that directly states the tool's purpose without any redundant or unnecessary words. It is well-structured and front-loaded with the key information, making it 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?

Given the tool has four pagination/format parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain pagination behavior, describe expected response fields, or provide guidance on when to use this tool versus address-specific alternatives. The agent receives only the core purpose but lacks critical context for correct invocation and interpretation of results.

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 already provides 100% description coverage for all four parameters (limit, order, offset, select), so the baseline is 3. The description does not add any additional meaning or context to these parameters; it merely states the overall purpose. No extra value is provided beyond what the schema already explains.

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 ('Get') and clearly identifies the resource (list of all addresses) with a distinctive qualifier ('with their first appearance on the blockchain'). This effectively distinguishes it from sibling tools like koios_address_info which target specific addresses, and from other list tools like koios_account_list.

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 implies usage for retrieving a comprehensive list of addresses via the phrase 'all addresses', which contrasts with sibling tools for individual address lookups. However, it does not explicitly state when to use this tool versus alternatives, nor provide any exclusion criteria or prerequisites. The usage context is only inferred.

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