awwwards-mcp

Overview Schema Source Related Servers Discussions Admin

create_design_brief

Read-onlyIdempotent

Generate a cited design brief from 2–5 Awwwards references and a project goal, including shared signals, evidence gaps, an interaction plan, and accessibility guardrails.

Instructions

Synthesize a cited design direction from 2–5 Awwwards site slugs plus a project goal. Uses cached detail (including its element list) and Motion DNA evidence first and fetches only missing details; includeStructure=true also runs a browser band analysis per reference. Returns one Markdown text block containing versioned JSON: shared signals vs one-site outliers, evidence gaps, an evidence-backed interaction plan, and reduced-motion/content/keyboard guardrails. The structuredContent field mirrors that JSON. Use search_sites to find slugs; use compare_sites for raw side-by-side DNA and analyze_page_structure for a band map — this tool synthesizes a brief; it does not score a build or run a motion census.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slugs": "<slugs>",
      "goal": "<goal>"
    },
    "name": "create_design_brief"
  }
}

Input Schema

Name	Required	Description	Default
`goal`	Yes	Project goal the brief must serve, e.g. 'a portfolio for a type foundry'; required and non-blank
`slugs`	Yes	Two to five distinct site slugs from search_sites (letters, digits, underscores or hyphens; no duplicates)
`audience`	No	Optional target audience; carried into the brief's direction summary
`maxBands`	No	Band cap for the optional structure pass (5-60, default 12)
`viewport`	No	desktop = 1440x900 (default); mobile = 390x844 iPhone-class with deviceScaleFactor 3, isMobile + hasTouch	desktop
`constraints`	No	Optional list of project constraints (max 20), e.g. 'no WebGL', 'must work without JS'
`waitStrategy`	No	'load' + settle works on heavy sites; 'networkidle' waits for total quiet	load
`includeStructure`	No	Also run analyze_page_structure for each reference (needs Playwright; one browser launch per site)

Output Schema

Name	Required	Description	Default
`goal`	Yes
`sources`	Yes
`version`	Yes
`audience`	No
`direction`	Yes
`constraints`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.18.0Nov 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "audience": {
+      "type": "string"
+    },
+    "constraints": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "direction": {
+      "additionalProperties": false,
+      "properties": {
+        "buildConstraints": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "elementSignals": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "frequency": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "sourceSlugs": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value",
+              "display",
+              "frequency",
+              "sourceSlugs"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "interactionPlan": {
+          "additionalProperties": false,
+          "properties": {
+            "accessibility": {
+              "type": "string"
+            },
+            "cursorHover": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "durationRange": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "median": {
+                      "type": "number"
+                    },
+                    "p25": {
+                      "type": "number"
+                    },
+                    "p75": {
+                      "type": "number"
+                    },
+                    "sourceSlugs": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "p25",
+                    "median",
+                    "p75",
+                    "sourceSlugs"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "easings": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "entranceReveal": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "scroll": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "staggerHints": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "cursorHover",
+            "scroll",
+            "entranceReveal",
+            "easings",
+            "durationRange",
+            "accessibility"
+          ],
+          "type": "object"
+        },
+        "limitations": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "motion": {
+          "additionalProperties": false,
+          "properties": {
+            "availableSourceSlugs": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "durationRange": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "median": {
+                      "type": "number"
+                    },
+                    "p25": {
+                      "type": "number"
+                    },
+                    "p75": {
+                      "type": "number"
+                    },
+                    "sourceSlugs": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "p25",
+                    "median",
+                    "p75",
+                    "sourceSlugs"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "easings": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "interactionSignals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "libraries": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "renderers": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "scrollModels": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "availableSourceSlugs",
+            "libraries",
+            "renderers",
+            "scrollModels",
+            "interactionSignals",
+            "easings",
+            "durationRange"
+          ],
+          "type": "object"
+        },
+        "outliers": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "frequency": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "luminanceBand": {
+                "enum": [
+                  "light",
+                  "mid",
+                  "dark"
+                ],
+                "type": "string"
+              },
+              "sourceSlugs": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value",
+              "display",
+              "frequency",
+              "sourceSlugs"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "palette": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "frequency": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "luminanceBand": {
+                "enum": [
+                  "light",
+                  "mid",
+                  "dark"
+                ],
+                "type": "string"
+              },
+              "sourceSlugs": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value",
+              "display",
+              "frequency",
+              "sourceSlugs",
+              "luminanceBand"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "sharedPatterns": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "frequency": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "luminanceBand": {
+                "enum": [
+                  "light",
+                  "mid",
+                  "dark"
+                ],
+                "type": "string"
+              },
+              "sourceSlugs": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value",
+              "display",
+              "frequency",
+              "sourceSlugs"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "structure": {
+          "additionalProperties": false,
+          "properties": {
+            "availableSourceSlugs": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "bandCounts": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "count": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "slug": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "slug",
+                  "count"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "repeatedTags": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "display": {
+                    "type": "string"
+                  },
+                  "frequency": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "sourceSlugs": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "value": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "value",
+                  "display",
+                  "frequency",
+                  "sourceSlugs"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "availableSourceSlugs",
+            "bandCounts",
+            "repeatedTags"
+          ],
+          "type": "object"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "technologySignals": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "frequency": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "sourceSlugs": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value",
+              "display",
+              "frequency",
+              "sourceSlugs"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "summary",
+        "sharedPatterns",
+        "outliers",
+        "palette",
+        "technologySignals",
+        "elementSignals",
+        "motion",
+        "interactionPlan",
+        "buildConstraints",
+        "limitations"
+      ],
+      "type": "object"
+    },
+    "goal": {
+      "type": "string"
+    },
+    "sources": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "evidence": {
+            "additionalProperties": false,
+            "properties": {
+              "detail": {
+                "enum": [
+                  "cached",
+                  "fetched",
+                  "unavailable"
+                ],
+                "type": "string"
+              },
+              "elements": {
+                "enum": [
+                  "cached",
+                  "unavailable"
+                ],
+                "type": "string"
+              },
+              "motion": {
+                "enum": [
+                  "cached",
+                  "unavailable"
+                ],
+                "type": "string"
+              },
+              "structure": {
+                "enum": [
+                  "captured",
+                  "unavailable",
+                  "not_requested"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "detail",
+              "motion",
+              "elements",
+              "structure"
+            ],
+            "type": "object"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "slug",
+          "title",
+          "evidence"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "version": {
+      "const": 1,
+      "type": "number"
+    }
+  },
+  "required": [
+    "version",
+    "goal",
+    "constraints",
+    "sources",
+    "direction"
+  ],
+  "type": "object"
+}

Changed6 schema fields changedv1.15.1Oct 30, 2026

addedInput schema / properties / audience / description

Added value: +"Optional target audience; carried into the brief's direction summary"

addedInput schema / properties / constraints / description

Added value: +"Optional list of project constraints (max 20), e.g. 'no WebGL', 'must work without JS'"

addedInput schema / properties / goal / description

Added value: +"Project goal the brief must serve, e.g. 'a portfolio for a type foundry'; required and non-blank"

addedInput schema / properties / includeStructure / description

Added value: +"Also run analyze_page_structure for each reference (needs Playwright; one browser launch per site)"

addedInput schema / properties / maxBands / description

Added value: +"Band cap for the optional structure pass (5-60, default 12)"

addedInput schema / properties / slugs / description

Added value: +"Two to five distinct site slugs from search_sites (letters, digits, underscores or hyphens; no duplicates)"

Changed1 schema field changedv1.14.0Oct 28, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv1.13.0Oct 25, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
Addedv1.9.0Oct 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses the caching strategy ('uses cached detail ... fetches only missing details'), the conditional browser cost of includeStructure ('one browser band analysis per reference'), and the exact return contract (one Markdown block with versioned JSON, mirrored in structuredContent). These are operational traits the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded: purpose first, then behavior, then return format, then routing. Every sentence carries information, though the sentence explaining the Markdown/JSON return partly overlaps an output schema that already exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, open-world synthesis tool with an output schema, the description covers inputs, caching/fetch behavior, cost of the optional structure pass, and the shape of the result. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter (including viewport geometry, waitStrategy tradeoffs, and maxBands range) is already documented in the schema. The description only restates the 2–5 slug range and repeats the includeStructure effect, adding little meaning beyond the structured fields — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Synthesize a cited design direction') plus its exact inputs ('2–5 Awwwards site slugs plus a project goal'). It then explicitly excludes sibling behaviors: 'it does not score a build or run a motion census', separating it from verify_build and the motion-census tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It routes the agent explicitly: 'Use search_sites to find slugs; use compare_sites for raw side-by-side DNA and analyze_page_structure for a band map.' It also states what the tool is not for, giving both when-to-use and when-not-to-use guidance.

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