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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes well beyond them: auth requirement, the 1000-entry cap, the null semantics of inbox_id on account-wide entries, and two concrete failure modes (400 invalid_list, inbox_not_found for another account's inbox). That is exactly the extra behavioral context annotations cannot carry.

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?

It is front-loaded with usage, then behavior, then inputs, then the return shape, then error cases — a logical order with no filler. It is dense, and the 'Inputs:' clause duplicates information already in the schema, which is the only thing keeping it from a 5.

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?

There is no output schema, so the description must carry the return contract, and it does: the full data array shape, the next_page_token for pagination, and the entry_type/inbox_id null semantics. Combined with the documented error codes, an agent has everything needed to call and interpret this tool.

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 all three parameters are already documented, including the enum meanings for direction and type. The description largely restates those same meanings in prose and adds no syntax or format detail the schema lacks, so the baseline 3 is appropriate.

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 opens with a specific verb and resource: 'the addresses on an allow or block list.' It is immediately distinguishable from siblings like cooper_create_list_entry, cooper_get_list_entry, and cooper_delete_list_entry, which operate on single entries rather than listing the full 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?

It states the triggering condition ('when you need the addresses on an allow or block list') and clarifies that the per-inbox task allowlist is a separate, unaffected concept. It does not, however, explicitly route the agent to cooper_get_list_entry for a single entry versus this bulk list call, so the alternative-selection guidance is contextual rather than explicit.

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