run_report

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

With annotations present (readOnlyHint=false, idempotentHint=true), the description adds real behavioral value beyond them: privacy defaults that differ from Gramps' own defaults, and the dual return path (file vs. background task_id). The background/polling behavior is exactly the kind of context an agent needs and no annotation conveys. It does not, however, state permissions or side effects of writing the file.

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 compact sentences, front-loaded with the action and return. The parenthetical option dump is slightly noisy but each sentence carries load (privacy defaults, return path, polling).

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?

With no output schema, the description carries the burden of describing return values and does so (file, or task_id to poll with get_task). Privacy semantics and the background-execution caveat are covered, leaving only permissions/error behavior unstated.

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, but the description adds genuine nuance beyond the schema by explaining that living_people/incl_private defaults diverge from Gramps' own defaults, and by connecting options/include_private to that behavior. This is meaningful added meaning, not just repetition.

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 verb+resource ('Generate a report and return the file it produced'), which clearly distinguishes it from list_reports and get_report_options among siblings. It stops short of naming those siblings explicitly, so an agent must infer the boundary from the domain.

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 a conditional trigger ('unless you pass those options or include_private') and explains polling via get_task, which is useful routing. However it never states when to call run_report vs. list_reports/get_report_options, nor any prerequisite (like needing a valid report_id from list_reports, which is only implied by the schema).

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