Skip to main content
Glama

Clarify brand values

brand_clarify

Resolve ambiguous brand values after brand_compile by submitting a clarification ID and answer, such as a hex color, role name, font, or yes/no. Returns updated identity and remaining count.

Instructions

Resolve an ambiguous brand value interactively. After brand_compile, some values need human confirmation — wrong primary color, unknown font, unassigned color roles. Pass the clarification item ID and the user's answer (hex color, role name, font name, or 'yes'/'no'). Supports natural language: 'the purple one is accent' or '#5544f2 is secondary'. Returns updated identity and remaining clarification count.

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": {
      "id": "<id>",
      "answer": "<answer>"
    },
    "name": "brand_clarify"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesClarification item ID from needs-clarification.yaml (e.g. 'clarify-1')
answerYesThe user's answer: a hex color (#ff0000), a role name (primary, secondary, accent, neutral, surface, text, action, tint, overlay, border, gradient, highlight; variants: surface-alt, text-secondary, neutral-alt, border-alt, accent-alt, action-alt), a font name, 'yes'/'no', or natural language ('the purple one is accent, the pink transparents are tint')

Output Schema

NameRequiredDescriptionDefault
_metadataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.18.0
    • changedInput schema / properties / answer / description
      Previous value: -"The user's answer: a hex color (#ff0000), a role name (primary, secondary, accent, neutral, surface, text, action, tint, overlay, border, gradient, highlight), a font name, 'yes'/'no', or natural language ('the purple one is accent, the pink transparents are tint')"New value: +"The user's answer: a hex color (#ff0000), a role name (primary, secondary, accent, neutral, surface, text, action, tint, overlay, border, gradient, highlight; variants: surface-alt, text-secondary, neutral-alt, border-alt, accent-alt, action-alt), a font name, 'yes'/'no', or natural language ('the purple one is accent, the pink transparents are tint')"
  2. Changed2 schema fields changedv0.17.0
    • changedOutput schema / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / _metadata / additionalProperties
      Previous value: -trueNew value: +{}
  3. Addedv0.14.1
  4. Removedv0.12.0
  5. Changed1 schema field changedv0.11.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": true,
      +  "properties": {
      +    "_metadata": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "next_steps": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "what_happened": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "what_happened",
      +        "next_steps"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "_metadata"
      +  ],
      +  "type": "object"
      +}
  6. First observedv0.5.0

TDQS

A4.1/5.0
Behavior4/5

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

Adds context beyond annotations: it is a human-in-the-loop interrupt that mutates stored brand identity, accepts natural-language answers, and reports remaining clarification count so the agent knows whether to loop. Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description does not address what happens on an unparseable answer or that repeated calls are non-idempotent, which keeps it from a 5.

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?

Four sentences, front-loaded with the action, then trigger, then parameter forms, then return. The example sentences ('the purple one is accent', '#5544f2 is secondary') partially duplicate the schema descriptions, which is the only redundancy.

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 2-param, fully documented schema with an output schema and annotations, the description supplies the essential missing piece — the workflow position relative to brand_compile — plus loop-termination info. A note on handling unrecognized answers would close the remaining gap.

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% and the schema already enumerates role names, variants, 'yes'/'no' and natural-language forms. The description restates the accepted answer types and gives similar examples, adding little syntactic meaning the schema does not already supply — 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?

Specific verb and resource: 'Resolve an ambiguous brand value interactively', with the exact payload it accepts (clarification item ID + user's answer). It also anchors itself to a sibling ('After brand_compile'), so an agent can place it in the workflow without opening other schemas.

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?

Gives an explicit trigger: after brand_compile, when values are ambiguous (wrong primary color, unknown font, unassigned roles). No explicit exclusions or named alternatives, but the precondition is concrete enough that the agent knows when to reach for it.

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