arc_agents_list

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

With no annotations provided, the description must carry the full transparency burden. It discloses that data comes from a 'validated hourly crawl' (implying potential staleness) and that unresolved agents are 'listed as UNRESOLVED, never silently dropped' – a valuable behavioral guarantee. It also states the tool is 'Paged', but omits ordering/sort behavior and any rate-limit or error semantics, which is a minor gap. Overall, it provides meaningful context beyond the schema.

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 well-structured and front-loaded with the core purpose. It packs a lot of information – fields, statuses, filters, paging, and a behavioral note – into a compact, readable block. Every sentence serves a purpose, though it could be slightly tightened by moving the column list or status enumeration into a more terse form. No fluff or redundancy.

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 no output schema, so the description must explain return values, and it does – listing the row fields (agentId, owner, agentURI, host, name, skills, status, x402, concentration). It also mentions pagination and the crawl freshness. Missing are ordering semantics and any error/edge-case handling, but for a filtered list tool this is largely complete. The omission of SKIPPED_ROBOTS in the status list is a minor completeness issue.

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 baseline is 3. The description adds a small grouping of parameters ('Optional filters: status, host, owner') and mentions 'Paged', which clarifies the role of limit/offset. However, it lists status values as 'OK | UNRESOLVED | INVALID', omitting 'SKIPPED_ROBOTS' which is a valid enum value in the schema – a potential source of confusion. This omission prevents the description from adding more value than 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 states a clear, specific purpose: 'List the ERC-8004 agents registered on Arc'. It names the resource (Arc agents) and the action (list), and it distinguishes itself from siblings like arc_agents_search and arc_agents_stats by the verb 'list'. The description also enumerates the fields returned, which reinforces its role as a broad listing tool.

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 does not explicitly state when to use this tool versus alternatives like arc_agents_search or arc_agents_stats. It implies listing and filtering via 'Optional filters: status, host, owner', but it never says 'use this for a broad overview' or 'use search for fuzzy queries'. No exclusions or alternative routing is provided, leaving the agent to infer the tool's niche from its name alone.

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