icloud-mcp

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

No annotations provided, so description carries full disclosure burden. It explains the purpose (maintaining progress across long operations) but omits mechanical details like whether entries append or overwrite, storage limits, persistence duration, or retrieval methods. Adequate but not rich in behavioral specifics.

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?

Three tightly constructed sentences with zero redundancy: (1) functional definition, (2) usage timing, (3) value proposition. Information density is high with no filler content. Well front-loaded with the core action.

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?

Appropriate for a single-parameter tool with no output schema. The description covers the operational lifecycle and intent. Could be improved by referencing the sibling log_read tool for retrieval or noting persistence characteristics, but sufficient for correct invocation.

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?

With 100% schema coverage, the baseline is 3. The description adds valuable semantic context beyond the schema's generic 'Description of what you are doing' by specifying content types: 'plan before starting' versus 'completed step,' guiding the agent on what content to provide in the step parameter.

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 opens with the specific action 'Write a step to the session log,' clearly identifying the verb (write) and resource (session log). It effectively distinguishes from siblings log_read (reading) and log_clear (clearing) through this explicit action statement.

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?

Provides explicit temporal guidance: 'Use this to record your plan before starting, and after each completed step.' This establishes clear when-to-use context for long-running operations. Lacks explicit negative guidance (when not to use) or direct sibling comparison, but the workflow pattern is clearly defined.

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