handmade

Overview Schema Source Related Servers Discussions Admin

handmade_design_brief

Converts a UI request into a complete design brief before coding, including fonts, contrast-checked colors, spacing, layout rules, and a self-check; asks clarifying questions when needs are missing.

Instructions

Before building a new UI, turn the user's request into a full design brief. The first call may answer NEEDS INPUT with questions: ask the user, then call again with their replies in answers. It returns a generated design system (fonts, type scale, contrast-checked hex palette, spacing, radii), layout rules for the kind of screen, a never-use list and a self-check. Follow the returned brief exactly when writing the code. Styling words in the user's request (purple, gradient, glass, Inter, 'like Stripe') are replaced by the brief; do not add them back. Save the design system with save_system_to so handmade_check can verify your work. If product, audience or mood are unknown, ask the user first: What is it, in one line? Name the product and what it does. | Who uses it and where? (for example: county health officers on office laptops) | Which mood fits? Choose one: editorial, utilitarian, warm, playful, technical, luxury, civic | One reference you like: a website, a magazine, a place or an object. (optional) | One thing people should remember about this screen. (optional)

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": {
      "request": "<request>"
    },
    "name": "handmade_design_brief"
  }
}

Input Schema

Name	Required	Description
`kind`	No	Type of screen. Detected if omitted.
`mood`	No	Overall feel.
`allow`	No	Comma-separated deliberate brand choices the rules should keep, for example 'purple'. Only when the user confirms it is their brand.
`fresh`	No	Ignore a saved handmade.system.json in project_path and start over.
`answers`	No	The user's answers to questions this tool asked, keyed by the question key. Only answers the user actually gave. Never fill these in yourself.
`proceed`	No	Write the brief even though facts are missing. Only when the user chose to skip the questions. Missing facts are then listed for you to leave as marked slots.
`product`	No	What the product is, in one line.
`request`	Yes	The user's UI request, in their words.
`variant`	No	Pick an alternative generated design system.
`audience`	No	Who uses it and where.
`reference`	No	A site, magazine, place or object the user likes.
`signature`	No	The one thing people should remember about the screen.
`project_path`	No	Absolute path of an existing project to reuse its fonts and colors.
`save_system_to`	No	Absolute path to write handmade.system.json (usually the project root). handmade_check reads it.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 11, 2026

TDQS

A4.3/5.0

Behavior4/5

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

No annotations are supplied, so the description carries the full burden and does well: it discloses the NEEDS INPUT protocol, the exact content of the returned brief, the rule that styling words in the request are replaced and must not be re-added, and the persist-to-file side effect via save_system_to. It stops short of stating failure behavior for bad paths or what a re-call with `fresh` vs. cached system does.

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?

Front-loaded with purpose, then flow, then constraints, then the literal question script — a sensible ordering. The closing question template is long but earns its place by giving the agent exact wording for the clarification turn; the enumerated return payload is slightly verbose but informative.

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

Completeness4/5

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

For a 14-parameter tool with a nested object, no output schema and no annotations, the definition covers return shape, conversational protocol, persistence target, and the constraint not to reintroduce replaced styling words. Remaining gaps are secondary param behaviors (`variant`, `fresh`, `project_path` reuse) that the schema descriptions largely handle.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: `answers` must contain only what the user actually said ('Never fill these in yourself' is echoed in the schema but reinforced), `proceed` is tied to the skip-questions path, and `save_system_to` is linked to handmade_check consumption. The `allow` / styling-word-replacement interplay is also clarified behaviorally.

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 first sentence names a specific verb and resource: 'turn the user's request into a full design brief' before building a UI, and the return payload is enumerated (fonts, type scale, palette, spacing, radii, layout rules, never-use list, self-check). This is clearly distinguishable from the inspection-oriented siblings (handmade_check, handmade_scan) which do not generate a brief.

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

Usage Guidelines4/5

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

Timing is explicit ('Before building a new UI') and the multi-turn flow is spelled out: first call may return NEEDS INPUT, then call again with replies in `answers`. It also routes the agent to a downstream step ('Save the design system with save_system_to so handmade_check can verify your work'). What is missing is an explicit when-not-to-use or a direct contrast naming sibling alternatives.

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

Deploy Server