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

Annotations already declare this is a non-destructive write in a closed world, so the safety profile is covered. The description goes meaningfully beyond them: it states the note is emitted via notes_save on the notes cadence, lists the three return artifacts (source key, cost line, tagged link with utm_campaign sf-giveaway-... or App Store campaign), and notes that it is free and one-at-a-time. It would be stronger if it said whether the post goes out immediately or how re-invocation behaves.

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 purpose is front-loaded, but the body is a single dense colon-and-parenthesis sentence that is hard to parse on first read. Most content earns its place, yet the packing of return values, field guidance and constraints into one run-on reduces scanability. Some restructuring into two or three sentences would preserve the information with less parsing cost.

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?

With 7 parameters, 5 required, no output schema, the description does cover the return payload and key constraints, which is the bulk of what an agent needs. Missing are the relationship to the preceding plan/state, whether the note publishes immediately or is queued, and any failure/retry behavior. Adequate but with notable gaps for a state-changing creation tool.

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 71%, and the description adds real meaning on top: it expands the shape enum values (result, credits, asset, seats), gives concrete examples for the ask field ('your site's URL', 'what you are stuck on'), and clarifies endsAt can be 'none' or must be within 30 days, and that unitCostUsd is supplied 'when known'. This compensates well for the partly described 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 conveys that this persists/starts a configured giveaway with a shape, audience, ask, cap and end date, which is more specific than the bare title. However, the opening phrasing 'Keep the giveaway the founder picked' is ambiguous about whether this creates a new giveaway or saves a plan, and it never distinguishes itself from sibling giveaway_plan, giveaway_mark, or giveaway_replies. An agent has to infer the purpose from field names rather than from a stated verb+resource.

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 only usage-shaped cues are 'Keep the giveaway the founder picked' (implying it runs after giveaway_plan) and 'One at a time', which is a sequencing constraint rather than guidance. There is no explicit statement of when to call this versus giveaway_plan or giveaway_mark, and no preconditions or exclusions are given. The agent must guess the workflow position.

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