Get Calendar Tasks

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds meaningful behavioral detail beyond those annotations: the endpoint documents no server-side filters, and correlation must be done manually using returned fields. It does not cover response shape or rate limits, but the main operational limitation is transparently disclosed.

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?

Two sentences with no filler: the first delivers the core purpose and context, the second isolates the important caveat. The most decision-relevant information, the lack of server-side filters, is front-loaded and clearly marked with a NOTE.

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 paginated list with three optional, fully documented parameters, the description is complete. It explains what the tool returns, the entity relationships, and how to compensate for the lack of server-side filtering via returned ID fields. No output schema exists, but the description still gives enough guidance for correct invocation and interpretation.

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%, with page, sort, and per_page all already described including defaults and bounds. The description adds the high-level note that results are sorted and paginated, and that server-side filters are unavailable, but it does not deepen parameter-level semantics beyond what the schema provides.

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 a specific verb ('List') and resource ('calendar tasks'), and expands on what calendar tasks are by naming the entity types they relate to (users, customers, jobs, estimates). It also implicitly distinguishes this from the sibling get_calendar_task_details tool by framing it as the sorted, paginated collection endpoint.

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 context: this tool lists all calendar tasks and supports sorting/pagination. It explicitly warns that no server-side filters exist, so an agent won't attempt to pass unsupported filter parameters. It does not explicitly name an alternative for single-task lookup, like get_calendar_task_details, so it stops short of full when-not-to-use guidance.

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