draft_event

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

With no annotations, the description fully carries the transparency burden. It discloses key behavioral traits: writes to /tmp/draft_event.json, uses Gemini, takes 30-90 seconds, enforces a single-event concurrency limit via shared state, and interprets times as Europe/London. This goes well beyond what annotations might have provided and gives the agent a clear mental model of side effects and constraints.

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 concise yet information-dense. Each sentence serves a purpose: purpose, usage guidance, timezone note, duration, concurrency warning, and cleanup pointer. No filler or repetition exists. It is well-structured, starting with the core action and then layering constraints.

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?

Despite having no output schema, the description tells the agent what to expect: a structured draft file with description and LinkedIn copy. It covers duration, concurrency, timezone handling, and how to reset state. The tool's simplicity (one parameter) means this description is fully sufficient for safe and 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?

The input schema already provides 100% coverage for raw_notes with a descriptive note about minimum length. The description adds extra semantic value by advising on content ('title, speakers, date/time, format') and clarifying timezone interpretation, which helps the agent craft a better raw_notes value. This elevates it above the baseline 3.

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's function: 'turn raw event notes into a structured draft (description, LinkedIn copy) via Gemini'. It specifies the resource (raw event notes) and output (draft written to /tmp/draft_event.json). It also distinguishes itself from siblings by framing this as 'Phase 1A', which separates it from later-stage tools like publish_event or schedule_linkedin.

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 clear context: this is the initial drafting step, and it tells users to provide as much detail as possible. It also warns about the one-event-at-a-time constraint and explicitly directs users to cleanup_state when abandoning a draft. However, it does not explicitly name alternatives for other scenarios or state when not to use this tool, so it falls short of a 5.

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