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

Beyond the readOnly and idempotent annotations, the description discloses important runtime behavior: the limit applies per source, pagination.total combines both sources, has_more indicates incomplete data, and callers must not compute utilization or overbooking until pagination is exhausted. This is critical, non-obvious behavior that could change how an agent interprets results.

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: sentence one defines the scope, sentence two gives pagination mechanics, and sentence three warns about the dangerous misuse. The most important caveat is included without burying the core purpose.

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?

The critical pagination behavior and per-source limit are well covered, and the readOnly/idempotent annotations handle the safety profile. But there is no output schema, and the description omits semantics for to_date, from_date, and employee_id, as well as the shape of the returned allocation entries, leaving notable gaps for an agent deciding how to construct a correct call.

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 description adds genuine meaning for limit and offset by explaining that the limit is applied per source and that offset should be advanced until has_more is false. However, to_date, from_date, and employee_id are not explained in either the schema or the description, and with only 40% schema description coverage the description needed to compensate more fully.

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 opens with a specific domain phrase, 'Unified capacity view,' and precisely states what is returned: BOTH manual resource allocations (tied to an activity type, not a project) AND project team allocations (project_team_members). This distinguishes it from project-only and allocation-mutation siblings without ambiguity.

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 gives clear context: use this tool when you need a unified view of both manual and project team allocations. It also clarifies that manual allocations are tied to activity types rather than projects. However, it never explicitly names an alternative tool or states when NOT to use this tool, so it stops short of full routing guidance.

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