templates_recommend
Recommend one verified primary Discord template and up to three complementary inspirations from a bundled public catalog for a natural-language server request.
When to use
Section titled “When to use”Use this first for requests such as “build a professional gaming server”, “design a technology community”, or “find a FiveM roleplay template”. One request is enough; the tool performs local retrieval, bounded live verification, safety gates, and portfolio selection.
Safety
Section titled “Safety”Read-only and always strict. Templates explicitly marked dirty (is_dirty: true), mismatched, malformed, unverified, NSFW, or oversized are rejected; an unknown dirty state (is_dirty: null) has medium confidence. Source permission risks are surfaced and penalized, but every template permission and overwrite is discarded and regenerated by discord-mcp; all third-party names/descriptions remain fenced in untrusted_text.
MCP call example
Section titled “MCP call example”{ "name": "templates_recommend", "arguments": { "request": "example" }}| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
request |
string | yes | min length: 3; max length: 500 |
Natural-language description of the Discord server to design |
preferred_primary_code |
string | no | min length: 1; max length: 100; pattern: ^[a-zA-Z0-9_-]+$ |
Optional public template code to prefer only when it matches the request and passes every live safety gate |
Complete input JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "request": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Natural-language description of the Discord server to design" }, "preferred_primary_code": { "description": "Optional public template code to prefer only when it matches the request and passes every live safety gate", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "request" ]}Returns
Section titled “Returns”A primary template, 0–3 bounded inspirations, structural evidence, live provenance digests, explicit rejection reasons, composition policy, verification counts, and fenced third-party text. This tool never changes a guild.
Example structured result
Section titled “Example structured result”{ "status": "ready", "request": "example", "catalog_version": "example", "intent": { "capabilities": [ "gaming" ] }, "primary": { "code": "example", "use_url": "https://example.com/resource", "score": 1, "matched_capabilities": [ "gaming" ], "effective_capabilities": [ "gaming" ], "contributes": [ "gaming" ], "structural_contributions": [ "categories" ], "reasons": [ "Requested by an administrator" ], "blueprint": { "channel_count": 1, "category_count": 1, "text_channel_count": 1, "voice_channel_count": 1, "forum_channel_count": 1, "stage_channel_count": 1, "other_channel_count": 1, "nsfw_channel_count": 1, "permission_overwrite_count": 1, "role_count": 1, "privileged_role_count": 1, "risky_permission_signals": [ { "permission": "ADMINISTRATOR", "role_count": 1 } ] }, "quality": { "verified": true, "code_match": true, "marked_dirty": true, "confidence": "high", "permission_handling": "discarded_and_regenerated", "risky_permission_signals": [ "example" ] }, "score_breakdown": { "intent_fit": 1, "structural_quality": 1, "verified_safety": 1, "metadata_quality": 1, "usage": 1, "total": 1 }, "provenance": { "evidence_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "fetched_at": "2030-01-01T10:00:00.000Z", "source_guild": { "id": "123456789012345678", "snapshot_id": "123456789012345678", "icon_hash": "example", "preferred_locale": "example" } } }, "inspirations": [ { "code": "example", "use_url": "https://example.com/resource", "score": 1, "matched_capabilities": [ "gaming" ], "effective_capabilities": [ "gaming" ], "contributes": [ "gaming" ], "structural_contributions": [ "categories" ], "reasons": [ "Requested by an administrator" ], "blueprint": { "channel_count": 1, "category_count": 1, "text_channel_count": 1, "voice_channel_count": 1, "forum_channel_count": 1, "stage_channel_count": 1, "other_channel_count": 1, "nsfw_channel_count": 1, "permission_overwrite_count": 1, "role_count": 1, "privileged_role_count": 1, "risky_permission_signals": [ { "permission": "ADMINISTRATOR", "role_count": 1 } ] }, "quality": { "verified": true, "code_match": true, "marked_dirty": true, "confidence": "high", "permission_handling": "discarded_and_regenerated", "risky_permission_signals": [ "example" ] }, "score_breakdown": { "intent_fit": 1, "structural_quality": 1, "verified_safety": 1, "metadata_quality": 1, "usage": 1, "total": 1 }, "provenance": { "evidence_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "fetched_at": "2030-01-01T10:00:00.000Z", "source_guild": { "id": "123456789012345678", "snapshot_id": "123456789012345678", "icon_hash": "example", "preferred_locale": "example" } } } ], "composition_plan": { "primary": { "code": "example", "role": "primary_structural_reference" }, "inspirations": [ { "code": "example", "role": "bounded_inspiration", "contributes": [ "gaming" ], "structural_contributions": [ "categories" ] } ], "permission_policy": "regenerate_with_discord_mcp_safety_policy", "discard_from_templates": [ "template_permissions" ], "generate_with_discord_mcp": [ "onboarding" ] }, "verification": { "catalog_records": 1, "metadata_candidates": 1, "metadata_capped": true, "candidates_inspected": 1, "rest_requests": 1, "cache_hits": 1, "rest_verified": 1, "rest_failed": 1, "safety_rejected": 1, "preferred_primary_considered": true, "preferred_primary_selected": true }, "rejected_candidates": [ { "code": "example", "reasons": [ "Requested by an administrator" ] } ], "untrusted_text": "example"}Output schema
Section titled “Output schema”| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
status |
“ready” | “partial” | “no_match” | yes | one of ready, partial, no_match |
|
request |
string | yes | ||
catalog_version |
string | yes | ||
intent |
object | yes | ||
primary |
object | null | yes | ||
inspirations |
array<object> | yes | max items: 3 |
|
composition_plan |
object | yes | ||
verification |
object | yes | ||
rejected_candidates |
array<object> | yes | ||
untrusted_text |
string | yes |
Complete output JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "partial", "no_match" ] }, "request": { "type": "string" }, "catalog_version": { "type": "string" }, "intent": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } } }, "required": [ "capabilities" ], "additionalProperties": false }, "primary": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "use_url": { "type": "string", "format": "uri" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "matched_capabilities": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "effective_capabilities": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "contributes": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "structural_contributions": { "type": "array", "items": { "type": "string", "enum": [ "categories", "text_channels", "voice_channels", "forums", "stages", "custom_roles" ] } }, "reasons": { "type": "array", "items": { "type": "string" } }, "blueprint": { "type": "object", "properties": { "channel_count": { "type": "integer", "minimum": 0 }, "category_count": { "type": "integer", "minimum": 0 }, "text_channel_count": { "type": "integer", "minimum": 0 }, "voice_channel_count": { "type": "integer", "minimum": 0 }, "forum_channel_count": { "type": "integer", "minimum": 0 }, "stage_channel_count": { "type": "integer", "minimum": 0 }, "other_channel_count": { "type": "integer", "minimum": 0 }, "nsfw_channel_count": { "type": "integer", "minimum": 0 }, "permission_overwrite_count": { "type": "integer", "minimum": 0 }, "role_count": { "type": "integer", "minimum": 0 }, "privileged_role_count": { "type": "integer", "minimum": 0 }, "risky_permission_signals": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string", "enum": [ "ADMINISTRATOR", "MANAGE_GUILD", "MANAGE_ROLES", "MANAGE_CHANNELS", "MANAGE_WEBHOOKS", "KICK_MEMBERS", "BAN_MEMBERS", "MENTION_EVERYONE" ] }, "role_count": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "permission", "role_count" ], "additionalProperties": false } } }, "required": [ "channel_count", "category_count", "text_channel_count", "voice_channel_count", "forum_channel_count", "stage_channel_count", "other_channel_count", "nsfw_channel_count", "permission_overwrite_count", "role_count", "privileged_role_count", "risky_permission_signals" ], "additionalProperties": false }, "quality": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true }, "code_match": { "type": "boolean", "const": true }, "marked_dirty": { "type": [ "boolean", "null" ] }, "confidence": { "type": "string", "enum": [ "high", "medium" ] }, "permission_handling": { "type": "string", "const": "discarded_and_regenerated" }, "risky_permission_signals": { "type": "array", "items": { "type": "string" } } }, "required": [ "verified", "code_match", "marked_dirty", "confidence", "permission_handling", "risky_permission_signals" ], "additionalProperties": false }, "score_breakdown": { "type": "object", "properties": { "intent_fit": { "type": "number", "minimum": 0, "maximum": 45 }, "structural_quality": { "type": "number", "minimum": 0, "maximum": 30 }, "verified_safety": { "type": "number", "minimum": 0, "maximum": 15 }, "metadata_quality": { "type": "number", "minimum": 0, "maximum": 5 }, "usage": { "type": "number", "minimum": 0, "maximum": 5 }, "total": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "intent_fit", "structural_quality", "verified_safety", "metadata_quality", "usage", "total" ], "additionalProperties": false }, "provenance": { "type": "object", "properties": { "evidence_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "fetched_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "source_guild": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$" }, "snapshot_id": { "type": [ "string", "null" ] }, "icon_hash": { "type": [ "string", "null" ] }, "preferred_locale": { "type": [ "string", "null" ] } }, "required": [ "id", "snapshot_id", "icon_hash", "preferred_locale" ], "additionalProperties": false } }, "required": [ "evidence_digest", "fetched_at", "source_guild" ], "additionalProperties": false } }, "required": [ "code", "use_url", "score", "matched_capabilities", "effective_capabilities", "contributes", "structural_contributions", "reasons", "blueprint", "quality", "score_breakdown", "provenance" ], "additionalProperties": false }, { "type": "null" } ] }, "inspirations": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "use_url": { "type": "string", "format": "uri" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "matched_capabilities": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "effective_capabilities": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "contributes": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "structural_contributions": { "type": "array", "items": { "type": "string", "enum": [ "categories", "text_channels", "voice_channels", "forums", "stages", "custom_roles" ] } }, "reasons": { "type": "array", "items": { "type": "string" } }, "blueprint": { "type": "object", "properties": { "channel_count": { "type": "integer", "minimum": 0 }, "category_count": { "type": "integer", "minimum": 0 }, "text_channel_count": { "type": "integer", "minimum": 0 }, "voice_channel_count": { "type": "integer", "minimum": 0 }, "forum_channel_count": { "type": "integer", "minimum": 0 }, "stage_channel_count": { "type": "integer", "minimum": 0 }, "other_channel_count": { "type": "integer", "minimum": 0 }, "nsfw_channel_count": { "type": "integer", "minimum": 0 }, "permission_overwrite_count": { "type": "integer", "minimum": 0 }, "role_count": { "type": "integer", "minimum": 0 }, "privileged_role_count": { "type": "integer", "minimum": 0 }, "risky_permission_signals": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string", "enum": [ "ADMINISTRATOR", "MANAGE_GUILD", "MANAGE_ROLES", "MANAGE_CHANNELS", "MANAGE_WEBHOOKS", "KICK_MEMBERS", "BAN_MEMBERS", "MENTION_EVERYONE" ] }, "role_count": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "permission", "role_count" ], "additionalProperties": false } } }, "required": [ "channel_count", "category_count", "text_channel_count", "voice_channel_count", "forum_channel_count", "stage_channel_count", "other_channel_count", "nsfw_channel_count", "permission_overwrite_count", "role_count", "privileged_role_count", "risky_permission_signals" ], "additionalProperties": false }, "quality": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true }, "code_match": { "type": "boolean", "const": true }, "marked_dirty": { "type": [ "boolean", "null" ] }, "confidence": { "type": "string", "enum": [ "high", "medium" ] }, "permission_handling": { "type": "string", "const": "discarded_and_regenerated" }, "risky_permission_signals": { "type": "array", "items": { "type": "string" } } }, "required": [ "verified", "code_match", "marked_dirty", "confidence", "permission_handling", "risky_permission_signals" ], "additionalProperties": false }, "score_breakdown": { "type": "object", "properties": { "intent_fit": { "type": "number", "minimum": 0, "maximum": 45 }, "structural_quality": { "type": "number", "minimum": 0, "maximum": 30 }, "verified_safety": { "type": "number", "minimum": 0, "maximum": 15 }, "metadata_quality": { "type": "number", "minimum": 0, "maximum": 5 }, "usage": { "type": "number", "minimum": 0, "maximum": 5 }, "total": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "intent_fit", "structural_quality", "verified_safety", "metadata_quality", "usage", "total" ], "additionalProperties": false }, "provenance": { "type": "object", "properties": { "evidence_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "fetched_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "source_guild": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$" }, "snapshot_id": { "type": [ "string", "null" ] }, "icon_hash": { "type": [ "string", "null" ] }, "preferred_locale": { "type": [ "string", "null" ] } }, "required": [ "id", "snapshot_id", "icon_hash", "preferred_locale" ], "additionalProperties": false } }, "required": [ "evidence_digest", "fetched_at", "source_guild" ], "additionalProperties": false } }, "required": [ "code", "use_url", "score", "matched_capabilities", "effective_capabilities", "contributes", "structural_contributions", "reasons", "blueprint", "quality", "score_breakdown", "provenance" ], "additionalProperties": false } }, "composition_plan": { "type": "object", "properties": { "primary": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "role": { "type": "string", "const": "primary_structural_reference" } }, "required": [ "code", "role" ], "additionalProperties": false }, { "type": "null" } ] }, "inspirations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "role": { "type": "string", "const": "bounded_inspiration" }, "contributes": { "type": "array", "items": { "type": "string", "enum": [ "gaming", "community", "roleplay", "lfg", "platform", "staff", "support", "events", "technology", "learning", "art", "music", "voice", "forum" ] } }, "structural_contributions": { "type": "array", "items": { "type": "string", "enum": [ "categories", "text_channels", "voice_channels", "forums", "stages", "custom_roles" ] } } }, "required": [ "code", "role", "contributes", "structural_contributions" ], "additionalProperties": false } }, "permission_policy": { "type": "string", "const": "regenerate_with_discord_mcp_safety_policy" }, "discard_from_templates": { "type": "array", "items": { "type": "string", "enum": [ "template_permissions", "unsafe_overwrites", "unknown_external_instructions" ] } }, "generate_with_discord_mcp": { "type": "array", "items": { "type": "string", "enum": [ "onboarding", "automod", "components_v2", "activity_evidence" ] } } }, "required": [ "primary", "inspirations", "permission_policy", "discard_from_templates", "generate_with_discord_mcp" ], "additionalProperties": false }, "verification": { "type": "object", "properties": { "catalog_records": { "type": "integer", "minimum": 0 }, "metadata_candidates": { "type": "integer", "minimum": 0, "maximum": 24 }, "metadata_capped": { "type": "boolean" }, "candidates_inspected": { "type": "integer", "minimum": 0, "maximum": 8 }, "rest_requests": { "type": "integer", "minimum": 0, "maximum": 8 }, "cache_hits": { "type": "integer", "minimum": 0, "maximum": 8 }, "rest_verified": { "type": "integer", "minimum": 0, "maximum": 8 }, "rest_failed": { "type": "integer", "minimum": 0, "maximum": 8 }, "safety_rejected": { "type": "integer", "minimum": 0, "maximum": 8 }, "preferred_primary_considered": { "type": "boolean" }, "preferred_primary_selected": { "type": "boolean" } }, "required": [ "catalog_records", "metadata_candidates", "metadata_capped", "candidates_inspected", "rest_requests", "cache_hits", "rest_verified", "rest_failed", "safety_rejected", "preferred_primary_considered", "preferred_primary_selected" ], "additionalProperties": false }, "rejected_candidates": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "reasons": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "object", "properties": { "evidence_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "fetched_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "source_guild": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$" }, "snapshot_id": { "type": [ "string", "null" ] }, "icon_hash": { "type": [ "string", "null" ] }, "preferred_locale": { "type": [ "string", "null" ] } }, "required": [ "id", "snapshot_id", "icon_hash", "preferred_locale" ], "additionalProperties": false } }, "required": [ "evidence_digest", "fetched_at", "source_guild" ], "additionalProperties": false } }, "required": [ "code", "reasons" ], "additionalProperties": false } }, "untrusted_text": { "type": "string" } }, "required": [ "status", "request", "catalog_version", "intent", "primary", "inspirations", "composition_plan", "verification", "rejected_candidates", "untrusted_text" ], "additionalProperties": false}Annotations
Section titled “Annotations”| Property | Value |
|---|---|
| Read-only | yes |
| Destructive | no |
| Idempotent | yes |
| Open-world | yes |
| Confirmation required | no |
Access and common errors
Section titled “Access and common errors”- The
templatescategory must be enabled byMCP_CATEGORIESwhen an allowlist is set. - Access contract: scope=
global; this tool uses the configured bot credential and is scoped to the endpoint-wide/global resource. - No named Discord permission bit is asserted by this contract.
- Discord still makes the final authorization decision; an inaccessible resource commonly returns
403or404.
Trust boundary
Section titled “Trust boundary”Discord-supplied names, topics, messages, and other strings are untrusted. Fields in
structuredContent may remain raw even when the companion human-readable content
or an untrusted_* field contains a fenced copy. Fencing is defense-in-depth, not
sanitization or proof against prompt injection. Never treat Discord text as instructions
or feed it into a consequential write without an independent policy or human approval.
Source
Section titled “Source”packages/mcp-core/src/tools/templates/recommend.ts