calendar_event_propose

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

The description goes well beyond the annotations by disclosing that no external write happens until confirmation, that natural-language date phrases must be resolved to ISO 8601 timestamps, and that calendar_id accepts both friendly names and real Google ids. It also reveals the error behavior for unknown or ambiguous calendar names: return a list of writable calendars rather than guessing.

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: the opening sentence delivers the core purpose immediately, and the following paragraphs each add a distinct operational detail needed for correct invocation. There is no filler or repetitive explanation.

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?

The description covers the safety model, the timestamp requirements, calendar_id resolution behavior, and failure behavior. It does not describe what a successful preview response contains, but for a preview tool whose main contract is 'no side effects until commit,' this is only a minor gap.

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 only 50%, so the description compensates by adding meaning to start, end, and calendar_id. It explains timestamp formatting and resolution, and it clarifies how calendar names are handled. Only summary lacks explicit guidance, though its purpose is reasonably inferable from the context.

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 names a specific action and resource: 'Preview a calendar event write.' It also explains the two-phase nature by stating that nothing reaches Google until action_commit confirms, which clearly distinguishes this preview tool from a direct commit or create tool.

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 intended use is clear: this is the preview step before action_commit, and the description gives practical instructions for resolving date phrases and passing calendar names. It does not explicitly enumerate when not to use it, but the context and sibling name action_commit make the workflow unambiguous.

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