check_publication_coverage

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

With no annotations provided, the description carries the full burden. It details the two specific silent failures checked and mentions REPLICA IDENTITY conditions. It does not explicitly state it is read-only, but given the 'check' nature, that is likely safe. A small gap is not mentioning any potential side-effects or permissions needed.

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 with short paragraphs, but the first sentence could be more concise. The bullet points in the second sentence are clear. Minor redundancy: 'Judgment tool.' could be integrated into the first line. Still efficient overall.

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 a single parameter, no annotations, and the presence of an output schema, the description covers the tool's purpose, usage context, parameter format, and behavioral details. The output schema handles return values, so no further explanation needed. Complete for a check 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?

The only parameter 'expected_tables' has zero description coverage in the input schema. The description fully compensates by explaining the format ('schema.table' strings) and default schema assumption (public). This adds essential meaning beyond the raw schema.

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 clearly states it is a 'judgment tool' that cross-checks published tables against an expected set, and explicitly describes the two silent failures it catches. This differentiates it from sibling tools like list_publications which just list publications.

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 tells the agent to 'Run this on the PUBLISHER' and explains the expected format for expected_tables ('schema.table' strings, bare names assume public). It also provides context for when to use it (to catch silent data loss) and implicitly when not to use it (not for listing or other checks).

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