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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description adds substantive traits beyond them: results are not an atomic cross-store snapshot, retained history stays readable when a program is disabled, deleted Training sessions are excluded, and evidence is never silently truncated. The pagination contract is unusually well disclosed (continue with next_cursor even after an empty activity page; null means exhausted; read_at is retained across pages), which is exactly the kind of behavior an agent cannot infer from annotations.

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?

Purpose is front-loaded and the remaining sentences are dense rather than padded, but it is a single long paragraph covering purpose, selection, pagination, consistency, and error recovery with no structural breaks, making it harder to scan. A few clauses restate schema content (cursor continuation, limit reduction) that could have been dropped without loss.

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 nested, two-branch, cursor-paginated search over a deeply nested activity schema, the description covers the selection model, per-source return contents, ordering, pagination termination, snapshot consistency, and retention semantics. Because an output schema exists, it correctly stops short of enumerating return fields, giving an agent everything needed to call it correctly across pages.

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 still adds value by clarifying that limit caps both the number of matching Employees selected and the number of activity records returned, and by stating result ordering (Employee ID then channel and Campaign ID for Simulation, or session ID for Training). It also enumerates the Employee selection modes (IDs, literal name/email, Groups/Dynamic Groups, active state) and warns that activity filters do not select Employees. It does not explain the TRAINING period.field choices, which the schema already covers well.

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 verb and resource: 'Inspect the retained evidence behind Employee Simulation and Training posture within one Organization.' It then names the two concretely distinct modes (SIMULATION returns campaign/channel participations with outcomes and source events; TRAINING returns assignments with lifecycle dates and MCQ answers), so an agent can distinguish this from searchEmployees and search_campaigns without opening a schema.

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 routes the agent: 'Use searchEmployees for summaries or comparisons,' and 'omit selection to browse' when no filter is needed. It also constrains the call shape ('Choose exactly one activity.source per call') and gives a recovery path ('If a page is too large, reduce limit or narrow selection and filters'), which covers both when to use this and when a sibling is the better choice.

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