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

Annotations already provide readOnlyHint and idempotentHint, but the description adds substantial context: RLS scoping, pagination limits (max 200), response fields (pagination.total, has_more/next_cursor), the design rationale for read-only creation, and the meaning of an empty result. This goes well beyond what annotations and schema provide, and it contradicts nothing.

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 front-loaded with its core purpose and every subsequent sentence carries distinct, high-value information: pagination caveat, read-only rationale, UI routing, and empty-result semantics. It is dense but not bloated; nothing is redundant or 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?

For a read-only list tool with an output schema and mostly self-explanatory filter parameters, the description covers the critical caveats: pagination counting, empty-result interpretation, and the absence of a create endpoint. It lacks explicit guidance on valid status values or filter combinations, but those are at least partially inferable from parameter names and the RLS-scoped context.

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 covers limit, cursor, and offset well with descriptions, but status, deal_id, and project_id are undocumented in both schema and description. The description reinforces cursor-related pagination semantics but does not explain filters. At 50% schema coverage, the description only marginally compensates for the undocumented parameters, so a 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?

Description uses a specific verb 'List' and identifies the resource as 'offer documents / proposals' with RLS scoping, making the tool's exact purpose clear. It also notes the tool is read-only and that no create counterpart exists, which distinguishes it from mutation tools. The resource is clearly distinct from contracts_get and other getter siblings.

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 provides explicit when-to-use context (listing proposals) and when-not-to-use guidance: do not create from raw fields, direct users to the Matrix UI's Offers screen for creation, and do not count paginated pages while has_more is true. It explains why proposals_create does not exist, giving a clear alternative path. This is strong behavioral routing beyond just stating the purpose.

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