icloud-mcp

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully clarifies the scope ('across all calendars') and field restrictions ('title/summary' rather than full-text search). However, it omits critical behavioral details expected for a search tool: whether the search is case-insensitive, supports partial matching/wildcards, pagination behavior, and the read-only nature of the operation.

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, well-structured sentence that is front-loaded with the action ('Search for events'). Every clause earns its place: 'by title/summary' defines the search fields, 'across all calendars' defines the scope, and 'within an optional date range' defines temporal constraints. No redundant or unnecessary text is present.

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 the tool's moderate complexity (3 simple parameters, no output schema, no annotations), the description adequately covers the primary functional aspects: what is searched (events), how (by title/summary text), where (all calendars), and temporal constraints. While missing details on matching logic and pagination, it provides sufficient context for an agent to understand the tool's basic contract.

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 description coverage is 100%, establishing a baseline of 3. The description adds minimal semantic value beyond the schema, though it does clarify that the date range is 'optional' (implied by defaults but not explicit in schema) and that the search covers 'summary' in addition to 'title' (potentially distinct fields). It does not provide additional context on query syntax or date format constraints beyond the schema.

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 tool searches for events by title/summary text across all calendars within a date range. It effectively distinguishes from 'get_event' (which likely retrieves by ID) and 'list_events' (which presumably lists events from a specific calendar without text search) by specifying 'across all calendars' and the text-based search mechanism. However, it does not explicitly clarify when to choose this over filtering via list_events.

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 through the verb 'Search' and the scope 'across all calendars,' suggesting use when looking for events by text across multiple calendars. However, it lacks explicit guidance on when to use this versus 'list_events' (e.g., 'use this when you need text search across all calendars instead of listing a specific calendar'). No alternatives or prerequisites are mentioned.

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