discord_restore_structure

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

Substantially exceeds the annotations: it explains why destructiveHint=false (additive only, never deletes or renames, with the stated rationale about stale backups becoming wipes) and echoes idempotency through the missing-only creation rule. It also discloses non-obvious mechanics (overwrites re-applied by role name, member overwrites skipped due to cross-server ID mismatch) and the required Manage Channels/Manage Roles permissions.

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?

Front-loads the preview-by-default warning, then scope constraints, then matching caveats, then permissions. Every sentence adds a distinct operational fact with no restatement of the name or schema.

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 nested-object, 4-param, permission-gated mutation with an output schema, the description covers safety model, two-phase invocation, entity-matching limits and auth requirements. Return values are handled by the output schema, so nothing critical is missing.

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 75% and already documents confirm and guild_id; the description adds the operational meaning of confirm (preview vs. apply lifecycle) and clarifies that roles, categories and channels are all created when missing, tying to include_roles. It adds little about the backup object's required fields, but the schema's const format and structure carry that.

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 and resource: restore a structure backup into a server, with the object being a serialized backup rather than a live plan, which separates it in spirit from discord_architect_apply. It never names a sibling explicitly, so an agent must infer that distinction from the 'backup' object shape.

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 clear operational sequence: the first call previews, and you re-call with confirm:true to apply. That is real when-to-use guidance for the two-phase workflow, but it offers no exclusion such as when to prefer architect_apply/compare_structure or what to do about entities that exist but differ.

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