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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description nevertheless adds genuinely useful behavior unavailable in structured fields: results drop empty fields and truncate long lists, with params.full: true as the escape hatch — this prevents an agent from misreading a truncated or pruned response as complete data.

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 front-loaded opening is fine, but the definition then collapses into a single semicolon-laden run-on catalog of forty-plus names with no grouping or line structure, and the "actions says what one takes, whole..." clause is close to unparseable. The list also spends significant length on names whose purpose is never stated (spent, hubs, gate, proof, recheck), so bulk is not converted into usable signal.

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 catch-all dispatcher over dozens of reads and views, the definition does the minimum: it establishes that an unnamed call enumerates everything and that truncated results can be expanded. What it omits is what any given view answers — the promise of "every name with what it answers" is delegated to a runtime call rather than described, which is a reasonable design but leaves the definition thin for a tool of this breadth.

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 coverage is 100%, so the baseline would be 3, but the description goes further by enumerating the actual parameter names accepted by each individual read (search, get, events, look, etc.), which the schema only gestures at with "Its inputs, as the list names them." It does not explain what the parameters mean or what the "?" marker signifies, keeping it below a 5.

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 opening "Read the map: name what to read and give its params" establishes a read verb and a dispatch mechanism, and the catalog makes the sub-resource surface concrete. However, "the map" is a metaphor rather than a named resource, and nothing distinguishes query from the read-adjacent siblings (ask, report, revise) — an agent must infer the split from naming alone.

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?

Only one routing rule is given ("With no name, every name with what it answers"), which covers the discovery case but nothing else. There is no guidance on when to prefer change/ask/report over query, and the sentence about "actions says what one takes, whole: params read ... action ... or verb" is too garbled to function as a routing instruction.

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