list_appeal_requests

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

Annotations already mark the tool as readOnlyHint=true, which the description's 'Fetch' confirms. However, the description adds no further behavioral details, such as pagination behavior, data freshness, what happens without filters, or any rate limits. Since annotations carry the read-only disclosure, the description adds minimal extra value beyond that.

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 a single concise sentence with no wasted words, front-loading the verb and resource. While more structured formatting (e.g., bullet points) could improve scanability, the brevity is efficient for a simple list tool.

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?

Missing output schema increases the need for the description to explain return format, pagination, or behavior when no parameters are provided. The description omits all of these, leaving the agent to guess. Completeness is insufficient for a tool with no output schema.

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% and parameter descriptions in the schema are clear ('Filter by Appeal ID', 'Filter by Constituent ID'). The tool description echoes these filters but does not add new meaning beyond the schema. 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 clearly states the verb 'Fetch' and the resource 'appeal requests', and lists the two filtering options (by appeal or constituent), distinguishing it from sibling tools like list_appeals (which lists appeals) and get_appeal_request (which retrieves a single request).

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 implies usage for fetching filtered lists but does not explicitly state when to use alternatives like get_appeal_request for single requests, nor does it explain when not to use the tool (e.g., if no filters are needed). Usage context is implied but not fully detailed.

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