list_meetings

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

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses that returns are paginated with totals for completed and cancelled, and that rows are summaries with transcripts/reports stripped to keep responses small. This adds meaningful behavioral context.

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 well-structured with bullet points for filters, but slightly verbose in parts (e.g., parenthetical 'compute the cutoff client-side'). However, every sentence adds value, and it avoids redundancy.

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 no output schema, the description covers return type (paginated records, totals, role_name field), partial nature of data, and references sibling tools for full detail. This is complete for a list tool with good annotations.

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?

Despite 0% schema description coverage, the description fully explains each parameter: role_id, candidate_id, status (with enumerated values), and scheduled_after (with ISO datetime format and usage examples). This compensates entirely for the lack of schema descriptions.

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 'List interviews for the authenticated HR user.' It uses a specific verb and resource, and distinguishes itself from sibling tools like get_meeting and get_report by noting that rows are summaries and full detail is elsewhere.

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 guidance on when to use filters (e.g., 'Use for last week / this month queries') and advises using get_meeting/get_report for full details. It also explains the role_name field as an easy way to surface recent roles.

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