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

Even though annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, the description adds substantial non-obvious behavior: RLS scoping, the 200-row maximum, the guaranteed presence of pagination.total plus has_more/next_cursor, and the critical warning that total must not be computed while has_more is true. This pagination pitfall is exactly the kind of behavioral context annotations cannot convey.

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 sentences with zero filler: the core purpose and RLS scope lead, followed by the filter summary and pagination contract, and the anti-pattern warning closes. Every sentence carries operational weight, and the most critical constraint (never total when has_more is true) is front-loaded in its own emphatic sentence.

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 output schema covers return fields, and annotations cover the safety profile, so the description only needs to handle routing and behavioral quirks — which it does thoroughly with RLS scope, limit caps, and pagination semantics. The one genuine gap is the missing date format for to_date/from_date, which could cause the agent to send an incorrectly formatted filter on its first attempt.

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 schema description coverage at 50%, the description helps by grouping the four undocumented parameters into filter categories — "project, employee, status, date range" — mapping them to project_id, employee_id, status, and to_date/from_date. However, it stops short of fully compensating for the gap: no date format is specified for to_date/from_date, and no semantics are given for how the filters combine, leaving the agent to guess on those details.

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 — "List time entries" — immediately establishing the operation. Adding "(RLS-scoped)" clarifies the visibility boundary, and the resource name "time entries" cleanly distinguishes this from the sibling timelog_get_expenses, timelog_get_activity_types, and timelog_get_loggable_projects tools without needing their schemas.

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 operational guidance on filters and pagination ("NEVER total these rows when pagination.has_more is true; page with next_cursor until it is false"), which tells the agent how to use the tool correctly. However, it never explicitly addresses when to use this tool versus alternatives like timelog_get_expenses, nor does it state any exclusions or conditions for preferring this over other timelog read tools.

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