project_evidence

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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower, and the description still adds real context: it distinguishes missing/broken references, missing locators, and reference presence, and warns that even a located citation needs inspection. That interpretive caveat is genuinely useful for an agent. It omits output shape and the meaning of ordering/limits, keeping it below 5.

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?

Four sentences, front-loaded with the core action and scope, and the caveats each carry information an agent needs to interpret results. Some density in the third sentence, but no filler.

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?

An output schema exists, so return values need not be described, and the description covers purpose, scope, and interpretation caveats well. However, with 0% parameter documentation it leaves limit and generations semantics dangling, which matters for a traversal tool with a default fan-out.

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 0% across four parameters, so the description must compensate and largely does not. It explains the role of project root and root_person_id and implies a generations cap ('up to 10'), but leaves limit and the generations default (4) unexplained, and the stated 10-generation cap is not tied to the parameter.

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 names a specific verb and resource: reviewing source references for birth/death/burial/residence/marriage events, in read-only mode. It is distinguishable from siblings like find_sources or project_coverage by its event-level evidence focus. It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 5.

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 gives scope (project root or root_person_id, ancestors up to 10 generations, closer ones prioritized) but never states when to choose this over find_sources, source_details, or audit_tree. The exclusions ('does not verify parentage or change data') hint at boundaries without routing to alternatives, so usage is only implied.

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