cross_db_overlap

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

With no annotations, the description carries the burden and discloses key behavior: fetching both sets, in-memory intersection, a 500K row cap per side, and cancellation support. This is strong transparency, though it doesn't discuss return format or error cases.

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?

Three sentences: purpose/example, handling mechanism, and limits/cancellation. Each sentence earns its place, with no filler or redundancy. The structure is front-loaded and scannable.

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 complex tool with nested parameters and no output schema, the description covers the core mechanics, limitations, and a real-world example. It doesn't explain the return value format or sample_size specifics, but these are inferable or covered by the schema, making it adequately complete.

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 is 3. The description adds minimal parameter-specific guidance (only mentions adding filters for large tables), but doesn't elaborate on source structure, sample_size behavior, or filter syntax beyond what 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 specific action ('Compare a field across two databases to find overlapping values') with a concrete example (email addresses across CRM and marketing databases). It clearly distinguishes this tool from siblings by focusing on cross-database intersection, which no other sibling handles.

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?

Provides clear context on when to use the tool (when cross-DB joins are limited) and practical guidance (add filters for tables larger than 500K rows). While no explicit alternatives are named, the context makes usage conditions clear.

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