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

Beyond the readOnly/idempotent annotations, the description explains important behavior: planned counts leaf tasks with overlapping plans, worked counts time entries in the window, and null KPIs must not be treated as zero. This prevents a serious misinterpretation and is valuable behavioral context.

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 three sentences with no filler: the first summarizes the report contents, the second clarifies counting and null semantics, and the third gives usage guidance. Each sentence earns its place and the most important details are front-loaded.

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 tool with no output schema, the description sufficiently explains the returned content, the meaning of KPIs, the time window, and null handling. It also provides sibling context and usage timing, making it complete for an agent to select and invoke correctly.

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 50%; project_id is described in the schema, while periodDays is not. The description compensates by explaining periodDays' default, max, and window semantics, including how planned vs. worked counts relate to the window. It does not add much for project_id, but that is already covered.

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 what the tool produces: a time report with planned vs. logged hours, billable split, and divergence tasks. It is specific about the resource (project) and the time window, and the sibling references in the usage sentence help distinguish it from get_project_alerts and get_task_stats.

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 explicitly says when to use the tool ('when someone asks how a period went, before writing any status update') and names related tools for adjacent concerns: get_project_alerts for risk and get_task_stats for delivery. This gives an agent clear contextual guidance.

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