list_reconciliation_issues

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

No annotations are provided, so the description carries the full burden. It discloses the categories of findings the tool surfaces and its read-only explanatory role, which is useful. But it says nothing about output shape, ordering, or whether the result can be empty or huge for a continent with many mismatches.

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?

Two sentences, front-loaded with the core action and the enumerated issue types. The list of five categories is dense but each earns its place by defining scope. Slightly long but justified by the tool's explanatory purpose.

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 one-parameter explanatory tool with no annotations and no output schema, the description adequately covers the 'what' and 'why' but leaves the 'how to call it' unanswered — parameter format is undocumented everywhere, and no return-shape hint 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 coverage is 0% — the lone 'continent' parameter has no description anywhere. The description mentions 'a continent' only implicitly, never stating expected format (name? ISO code? case-sensitivity?) or whether an unknown continent errors or returns empty. This is the main gap.

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 + resource ('list every disagreement') and an explicit scope ('reconciling the three sources for a continent'). It enumerates five concrete categories of issue, which distinguishes it sharply from siblings like describe_methodology or get_country_metric.

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 a clear use case ('Use this to explain any number's coverage'), which tells the agent when to reach for this tool. However, it does not name or exclude a direct alternative sibling, and gives no counter-case for when NOT to call it.

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