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

Annotations already establish a safe, closed-world read, so the description's job is to add interpretation context — and it does: it warns that saved hours are 'unproven' when under half the month is documented and it flags `hoursAssumed` as a full-time default rather than measured data. Those are real caveats an agent would otherwise get wrong. It says nothing about failure modes (unknown rolePageId, wrong page type) or the cost/size of the response.

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 scope statement is front-loaded, which is good, but the core is a single sprawling sentence built from semicolon-chained nested lists (kinds of work, new-work subtypes, stage values) that is hard to parse on first read. Every element is arguably load-bearing for a tool with no output schema, but the structure could be broken into scannable clauses or a short list.

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?

No output schema exists, so the description must describe returns, and it does so thoroughly — baseline vs current hours, event timing, adopted work and settlement, role sizing, documentation coverage, and analysis stages with their enum meanings. The main omission is error/edge behavior and confirmation of what identifies a valid ROLE page.

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?

With only two parameters at 100% schema description coverage, the schema already carries the semantics, including the personal-token/workspace rule. The description adds no meaning about rolePageId beyond the schema's 'The ROLE page's id.'. `hoursAssumed` is referenced but it is a response field, not a 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 title plus opening phrase 'One ROLE page's story' gives a specific resource and scope, and the body enumerates exactly what data the page story contains (hours by work kind, what landed, new work, role size, latest analysis). An agent can tell this is a per-role read rather than a listing tool. It stops short of naming the near neighbors it differs from (compass_roles_overview, compass_pages_get, compass_transformations_read).

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?

There is no statement of when to call this versus compass_roles_overview, compass_pages_get, or compass_transformations_read, and no preconditions (e.g. that rolePageId must reference a ROLE-type page). The closing directives ('say so' when documentation is thin, 'talk about the role, never about a person') guide how to narrate the output, not when to select this tool.

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