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

Annotations only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses the auth/role requirement, the DRAFT-only state gate, and the two-step preview→commit protocol bound by a previewHash. It also flags a security-sensitive behavior (CDKey values must not be passed through the model) and the option to retain existing prize inventory instead of re-entering it. Gaps remain on failure/rollback behavior and what a successful save returns.

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 short, semicolon-delimited and front-loads the state gate before the procedure, with no filler sentences. The telegraphic style ('CDKey勿给模型') is efficient but slightly cryptic for a non-native reader, and the ordering of the inventory hint at the end feels appended.

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?

This is a complex write tool with a deeply nested config object, 0% schema description coverage and no output schema, so the description should explain more of the payload shape. It covers the orchestration (preview, hash, consent) and the CDKey policy well, but leaves requirements, requireAppCheckin, prize fields and activityRef unexplained. An agent could follow the save protocol but would be guessing at the config contents.

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 0%, so the description must explain five parameters; it clarifies the interaction among preview, previewHash and consent, and hints at cdkeys versus reuseFrom in the prizes array. However, activityRef, config.title, config.rules, config.requirements and requireAppCheckin receive no semantic explanation anywhere. It compensates for the trickiest parameters but leaves the bulk of the nested config undocumented.

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 prerequisites ('登录/主办方;仅DRAFT') and a workflow rather than stating plainly that it configures a raffle draft for an activity. The verb 'save' (保存) and the DRAFT restriction imply a write to a draft raffle, but the actual purpose must be inferred from the tool name/title. It is distinguishable from get_activity_raffle or act_activity_raffle only indirectly via the preview/save protocol.

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?

It gives a concrete procedure: preview first to verify the configuration, then re-submit the same parameters plus previewHash, consent=true and preview=false to save. It also states the hard precondition (logged in as organizer, activity must be in DRAFT) and a policy exclusion (CDKeys must not be handed to the model and must be configured by the person in the App). No sibling tool is named as an alternative, which keeps it from a 5.

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