commands_create_guild

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

Annotations already carry the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds writer-readable 'upser t' semantics that corroborate the idempotent hint, plus the propagation-timing behavior that annotations cannot express. No contradiction with annotations.

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?

Compact two-section layout with the purpose front-loaded and every line earning its place. Loses one point because the Returns block is likely redundant if the output schema already specifies the response shape.

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?

For a 15-parameter tool with a nested options object, the description covers the core decision (guild scope, propagation latency, return shape) but doesn't guide the complex optional surface or clarify type/options semantics. An agent can make the minimal required call, but richer command definitions risk being built incorrectly.

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 only 13%, so the description must compensate for 15 params — but it only implies guild scope (guild_id) and slash-command type. The large optional surface (options, contexts, intigration_types, dm_permission, nsfw, channel_types) and the nested option structure remain unexplained in both schema and description.

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?

States a specific verb + resource: 'Create or upsert a guild-scoped slash command.' The contrast with global ('propagate immediately vs ~1h for global") also differentiates it from the sibling commands_create_global without needing to open that tool's schema.

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?

Gives a concrete, decision-relevant context: guild commands propagate immediately versus roughly an hour for global commands, which tells an agent when the guild-scoped variant is preferable. But the guidance is imlied rather than an explicit when/when-not, and the overlap with commands_modify_guild for editing params is not addressed.

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