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

Annotations only mark the operation as read-only and idempotent. The description adds meaningful behavior beyond those: permission-scoped row visibility despite a workspace-wide table, the 200-row cap, pagination.total, has_more/next_cursor, and an explicit warning not to total rows while more pages exist.

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?

Four concise sentences, all substantive, with the core purpose front-loaded. Each sentence contributes either scope guidance, filter information, or a critical pagination warning; there is no filler.

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?

Given that annotations cover safety, an output schema exists, and the schema documents most parameters, the description fills the remaining critical gaps: permission scope, the workspace-wide underlying table, and the pagination contract. Nothing essential is missing for correct invocation.

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 78% schema description coverage, the input schema already explains most parameters. The description summarizes the filter groups and emphasizes pagination behavior, but it does not add much individual parameter detail beyond what the schema provides, so the baseline 3 is appropriate.

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 the specific verb and resource 'List expenses' and then expands with optional filters and a key scope detail (own rows vs workspace-wide). This clearly distinguishes it from sibling timelog_get_entries 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?

It conveys when to use the tool through the permission-dependent scope explanation and the pagination requirements. It does not explicitly state 'use this for expense listings, not time entries,' but no direct alternative expense-list sibling exists, so the context is sufficient.

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