guild_blueprint_plan

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

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description greatly expands on this by disclosing that no Discord mutation or checkpoint is written, that deterministic plan material may persist locally, that the tool resolves bots/guilds from environment variables, fails closed on ambiguity, preserves unrelated resources, and that the token is not standalone authorization. This rich context goes far beyond annotations and fully aligns with them.

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 long but well-structured with bold headers (Purpose, When to use, Safety, Returns). It is front-loaded with purpose and every section adds necessary detail. It could be slightly trimmed, but the length is justified for a complex orchestrating tool with safety considerations.

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 purpose, usage guidance, safety/behavioral details, and expected return values. Given the tool's complexity and the presence of an output schema, this is comprehensive. It also explicitly mentions verified source evidence, blueprint, bindings, dry-run ops, blockers, and plan_ref, ensuring the agent understands the full invocation context.

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 100% with parameter descriptions, so the baseline is 3. The description adds meaningful param-related semantics by explaining omission behavior (e.g., 'resolves an omitted guild only from DISCORD_DEFAULT_GUILD_ID or exactly one ALLOWED_GUILDS entry') and the rule that 'Explicit values are never overwritten and must match the locked profile.' These are not in the schema and help the agent choose correct parameter values.

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 uses a specific verb phrase 'Build, create, or design a complete Discord server' and clearly scopes the resource as a Discord guild. It distinguishes itself from siblings by explicitly positioning it as the required first step before `guild_blueprint_apply` and by contrasting it with manual chaining of template, role, channel, onboarding, AutoMod, and Components V2 tools.

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 'When to use' section explicitly says this is the required first step for unqualified build/design/create server requests, provides examples, and clarifies that 'server' means Discord guild. It also tells the agent to call it immediately instead of asking clarifying questions or manually chaining other tools, giving clear guidance vs alternatives.

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