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

Goes beyond annotations by explaining the device-code flow (displays a short code like BRAND-7K4X, then polls for completion), that no token copy-paste is required, that login is a magic-link fallback, and that studio_url must be a trusted origin configured via an env var. The one gap is that the 'logout'/credential-clearing and destructiveHint=true side effects are not elaborated on, and the description never references the write/destructive profile the annotations declare.

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-loaded with the primary action and the preferred mode before the alternatives, and the exclusion sentence is well placed at the end. Some redundancy exists between the prose mode list and the enum descriptions, but no sentence is wasted overall.

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?

With an output schema, full annotation coverage, and 100% schema description coverage, the description supplies the remaining needed context: mode selection strategy, trigger phrases, exclusions, and the trusted-origin constraint. Only the consequences of the destructive 'logout' path are left implicit.

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 description coverage is 100% and the enum descriptions already explain each mode, so the description's mode rundown largely repeats structured data. It adds only light context (the example code format and the preferred/fallback ordering), not new semantics for key, email, or studio_url.

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 ('Activate Brandcode Studio connection for saving and pushing brands') and enumerates the five supported modes. It also explicitly carves out sibling capabilities ('NOT needed for extraction, preview, or brand_check'), so an agent can distinguish it from brand_check, brand_compile, brand_export, etc. without opening a schema.

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 explicit when-to-use triggers ('save their brand to Studio', 'activate', 'connect to Brandcode') and when-not ('NOT needed for extraction, preview, or brand_check'). It also names 'activate' as the preferred mode and positions 'login' as a fallback, which is exactly the routing guidance an agent needs across the 5-value enum.

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

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

Annotations already declare it is not read-only, is open-world, and is destructive=false. The description adds useful behavior beyond annotations: pull downloads an existing hosted brand, save uploads the local .brand/ to Studio, save requires prior auth, and it returns brand name, slug, sync token, and connection details.

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?

The description is front-loaded with the core action and modes, then provides trigger phrases and return information. The sentences are dense but each adds useful selection or invocation context.

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 3-parameter tool with an output schema and annotations, the description covers the important gaps: mode behavior, default mode, auth prerequisite for save, trigger phrases, and return fields. Nothing critical is missing for an agent to invoke it correctly.

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 description coverage is 100%, so the schema already documents url, mode, and share_token in detail. The description reinforces the mode semantics and the url requirement for pull, but mostly repeats structured schema information and does not add much about share_token.

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?

The description states a specific verb and resource: connect a local .brand/ to Brandcode Studio. It clearly distinguishes the two modes and names the related auth sibling, so an agent can distinguish this from general brand tools.

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?

It gives explicit user-language triggers such as 'connect to Brandcode', 'pull from Studio', and 'save brand to Studio', and notes that save mode requires prior auth via brand_brandcode_auth. It does not specify when-not to use it or name an alternative connect tool, so it is strong but not fully exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), yet the description still adds non-obvious behavior: the <50ms latency budget, the hard prerequisite that brand_compile ran first, and that failures return specific actionable fixes rather than a bare verdict. The latency and prerequisite facts are not derivable from any structured field and materially affect how an agent should call this.

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-loaded with the one-line identity, then behavior, then an explicit alternative-routing block. Sentences are dense but every clause carries routing or prerequisite information; nothing is padding.

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 4-param read-only linter with a full output schema, the only gaps an agent could hit are the prerequisite and the return shape, and both are covered. Sibling disambiguation is fully handled, so the description is complete enough to call correctly on first attempt.

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 100%, so baseline would be 3, but the description adds real semantic depth per input: text is checked for voice/never-say/AI-isms, color for palette match with ΔE perceptual distance, font for typography match, css for anti-pattern violations. It also makes clear the parameters are composable (any combination) rather than mutually exclusive, which the schema's flat property list does not convey.

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?

"Inline brand linter" plus a concrete verb-and-scope statement: a sub-50ms pass/fail check over any combination of text, color, font, or css. It goes further and names the three sibling tools it is NOT (brand_check_compliance, brand_audit_content, brand_preflight), so an agent can discriminate it without opening any schema.

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?

Explicit when-to-use is given as a workflow pattern ("call this WHILE writing content or code, the way you call a type-checker... write a sentence, brand_check it, fix, continue"), plus a stated prerequisite (brand_compile must have run first). Three explicit when-NOT clauses route the agent to the correct alternative for publish gating, 0-100 scoring, and HTML/CSS rule violations.

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

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

Annotations already flag this as a non-readonly, non-idempotent mutation, and the description adds genuinely new context: it is a human-in-the-loop step, it consumes a clarification item ID, and it returns updated identity plus remaining count. It does not say what happens on an invalid or already-answered item, which is the main remaining gap.

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-loaded with the purpose, then prerequisites, then parameter forms, then return. Four sentences, all functional, though the answer-format sentence partly duplicates the schema and could be trimmed.

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?

An output schema exists so return values need no elaboration, and the description correctly avoids dwelling on them beyond a one-line summary. Prerequisite state and input flexibility are covered; only error and idempotency behavior for repeat answers is unstated.

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 100% and the description's list of accepted answer forms (hex, role name, font, yes/no, natural language) restates what the schema already documents, including the identical example style. Baseline 3 is appropriate — no net new parameter meaning is added.

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 ('resolve an ambiguous brand value interactively') and immediately scopes it to the post-brand_compile state, which separates it from compile/status/report siblings. An agent knows exactly what this does without opening the schema.

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?

The prerequisite is explicit ('after brand_compile, some values need human confirmation') and the triggering conditions are enumerated (wrong primary color, unknown font, unassigned color roles). It lacks an explicit 'do not use if…' or a named alternative, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description adds which files are written, the conditional Session 2+ branch producing visual-identity-manifest.md and system-integration.md, and what is returned. It stops short of saying whether existing outputs are overwritten or what failures look like.

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?

The main action and its artifacts are front-loaded, and the prerequisite/return information follows in a logical order. The enumeration of five-plus filenames is dense but each item conveys real information about outputs, so it largely earns its space.

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?

With an output schema present, the description needn't explain return values, yet it still summarizes them (token counts, clarification items, file list). Prerequisites, input file, conditional outputs, and the 'brand contract for AI agents' framing are all covered; only overwrite/failure behavior is left implicit.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description instead usefully characterizes the implicit input source (core-identity.yaml) and the Session 2+ data condition.

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?

The description states a specific verb (generate/compile) plus the exact artifacts produced (tokens.json, brand-runtime.json, interaction-policy.json, DESIGN.md) and the source it transforms (core-identity.yaml). This clearly separates it from siblings like brand_runtime, brand_export, or the brand_extract_* family.

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?

It explicitly names the prerequisite extract tools (brand_extract_web, brand_extract_site, brand_extract_visual, brand_extract_figma) and the 'Use after' ordering, which is strong context. It does not state when-not to use it or how it relates to downstream siblings such as brand_export or brand_report.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: deterministic fixed-table mapping, no inference, and explicit no-match reporting rather than guessing — which tells the agent how to interpret a thin result. It loses a point only because it recaps the return fields (context, output_contract, matched_selectors, no_governed_match) that the output schema already declares.

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-loaded with the core purpose and the primary routing instruction, and the NOT-clause closes it well. The middle is dense — four example trigger phrases plus a determinism paragraph — so it is slightly longer than needed, but every sentence carries routing or behavioral information.

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 read-only 4-parameter selector with a full output schema, this covers everything an agent needs: what it returns, what determinism guarantees, how misses surface, and which sibling to use instead. No gap remains that would cause a wrong call.

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 100%, so the baseline is 3. The description adds real meaning on top: it explains that task_type drives selection via a fixed table with visual-vs-copy-vs-mixed routing, and that audience matching is normalized-substring against governed persona names with an explicit no-match. It does not further explain budget or channel beyond the schema.

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 ("select a task-scoped brand context from the compiled runtime") and immediately contrasts it with the two siblings that do something else (brand_runtime for the full runtime, brand_check for auditing finished content). An agent can distinguish this from all 11 siblings without opening a schema.

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 explicit trigger phrases ("write this in our voice", "build a landing page") plus a clear negative clause naming the alternatives: "NOT for reading the entire runtime (use brand_runtime) or checking finished content (use brand_check)". When-to-use and when-not-to-use are both present.

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

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

Annotations mark this non-readOnly but idempotent and non-destructive; the description adds valuable context beyond that: it writes files to .brand/exports/<file>, returns full content for markdown targets versus a generation summary for pdf, and has a prerequisite compile step. It doesn't state overwrite behavior for existing files at the same path, which is the one remaining ambiguity.

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-loaded with purpose, then triggers, then per-target semantics — a sensible order. The target enumeration is long and partly redundant with the enum, but each clause is information-dense rather than filler.

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?

With an output schema present, the description needn't explain return shapes, yet it helpfully notes that markdown targets return full content while pdf returns a summary. Prerequisite, write location, and sibling exclusion are all covered; only overwrite/collision behavior on repeated exports is unaddressed.

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 100% and the enum already documents every target value, so the target enumeration mostly repeats structured data. The include_logo guidance ('set false to drop the embedded SVG/data URI when size matters') does add a decision rationale beyond the schema's terser 'reduce file size.' Baseline 3 is appropriate.

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?

Opens with a specific verb+resource ('Bundle the compiled brand system into a portable artifact') and enumerates each target destination with what each produces. This makes the export capability fully distinguishable from siblings like brand_compile and brand_preview.

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 concrete trigger phrases ('share my brand', 'export for ChatGPT/Cursor/team'), states a prerequisite (brand_compile must have run), and explicitly excludes the sibling case: 'NOT for previewing one section — use brand_preview.' Both when-to-use and when-not are covered.

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

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

Annotations already declare this as a safe, read-only, idempotent operation, and the description adds meaningful behavioral context: what 'check' returns (pass/warn/fail per rule), what 'rules' does without checking content, and the overall return shape. No contradictions.

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?

The description is front-loaded with the core action and scope, then mode behavior, use timing, and exclusions. Every sentence contributes useful routing or behavioral information.

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?

With rich annotations, full parameter schema coverage, and an output schema, the description fills the remaining gaps: mode semantics, when to use it, and which sibling alternatives to use instead. An agent has enough to call it correctly.

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 description coverage is 100%, and the schema already documents the html string/file-path behavior and the mode enum. The description restates these semantics but adds no additional parameter nuance beyond the schema.

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?

The description gives a specific verb and resource — checking HTML/CSS against brand rules — and lists concrete violation types. It also distinguishes itself from brand_audit_content and brand_audit, but does not explicitly differentiate from the sibling tool brand_check.

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?

It states exactly when to use the tool (after generating visual content), explains both modes, and explicitly names two non-use cases with alternative tools. The agent has clear routing guidance.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true; the description adds useful behavior beyond that — output is a written file at a specific path, the HTML is self-contained and works offline. It doesn't discuss whether re-running overwrites the prior report, though idempotentHint implies it. No contradiction with the write annotation.

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?

Three front-loaded sentences: what it produces, how it behaves (offline/self-contained) and where it writes, then the sequencing prerequisite and return contents. No filler or repetition of the title.

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 zero-parameter tool with an output schema and full annotations, this covers everything an agent needs: prerequisite order, write location, artifact portability, and what comes back. 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?

Zero parameters, so the baseline is 4. The description correctly presents this as a no-argument operation and focuses on output artifacts instead of inventing configuration options.

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 artifact: 'Generate a portable HTML brand identity report' with the exact contents (logos, color swatches, typography, tokens). The output location '.brand/brand-report.html' makes it unmistakable versus siblings like brand_export or brand_compile.

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 an explicit prerequisite ('Use after brand_compile') and a concrete downstream use case (upload to an AI chat as brand guidelines). It does not name when to skip it or contrast with brand_export, which is the main remaining gap.

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

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

Far exceeds the annotations: it discloses Live Mode behavior (refresh from hosted runtime per call, subject to cache TTL) and a silent fallback to the local mirror on network error, which is the kind of failure-mode detail an agent cannot get from the schema. It also quantifies token cost per slice and restates read-only in prose, consistent with readOnlyHint=true.

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-loaded with the resource identity and the slicing contract, with live-mode caveats and the refresh pointer at the end where they belong. Slightly over-dense: the per-slice token counts are repeated almost verbatim from the schema, costing a sentence that earns little.

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?

An output schema exists, so return values need no explanation, and the description covers everything else an agent needs: how to size the response, where the data comes from in live vs offline mode, and how to force a refresh. Nothing material is missing for a zero-required-parameter read tool.

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 100%, so the baseline is 3, but the description adds rationale beyond the enum docs — why to slice (token cost, agent satisficing) and the approximate payload sizes. The slice contents themselves are essentially a restatement of the schema descriptions.

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 (read the compiled brand runtime contract, brand-runtime.json) and immediately describes what the content is: the brand system agents load as context. The closing 'Run brand_compile to refresh' implicitly separates it from the compile sibling, so an agent can tell read-from-cache apart from rebuild.

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 concrete usage guidance for the slice parameter ('Use slices when passing brand context to sub-agents — smaller context reduces token cost and agent satisficing') and names the prerequisite tool for refreshing. It does not explicitly contrast with brand_context or brand_export, so the when-not case for the closest siblings is left to inference.

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

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

Annotations declare it is a non-destructive, idempotent, open-world write, but the description goes well past that: it names the exact artifacts produced in auto mode (DTCG tokens, design-synthesis.json, DESIGN.md, brand runtime, interaction policy, HTML report) and explains the already-exists behavior. The privacy explanation on local discovery is additional context an agent needs before prompting the user.

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-loaded with purpose, then triggers, then parameter contract, then exclusions — a sensible order. It is dense rather than padded, though the long trigger-phrase enumeration and the parenthetical artifact list make it longer than strictly necessary for an agent that already sees a 100% covered 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?

An output schema exists, so return values need not be explained, and the description instead covers the decision-relevant surface: which source param to pick, what auto mode does, what happens when .brand/ already exists, and where to go for adjacent intents. Nothing needed 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.

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantics on top by explaining the mutual exclusivity of the four source parameters, the no-source fallback, and the specific interaction of mode='auto' with website_url. It does not repeat the enum or URI formats, which the schema already carries.

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?

Opens with a specific verb+resource ('Adopt a brand into a portable .brand/ runtime') and enumerates the four source types it accepts. The closing sentence explicitly distinguishes it from brand_runtime, brand_context, and brand_brandcode_connect, so an agent can route correctly without opening any schema.

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?

States when to use it in the user's own phrasing ('use my existing brand guidelines with AI', 'I have a PDF brand guide', 'use our Figma library'), and gives explicit exclusions pointing to the named alternatives. It also covers the degenerate case (no source passed → discovery menu) and the idempotent case (.brand/ exists → status returned).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile needs no restating. The description adds real behavior beyond them: the full getting-started guide returned when no .brand/ exists, and the confidence/completion dimensions reported. It stops short of describing caching, cost, or size of the returned status payload.

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-loaded with the core action, then details, then usage triggers, then the fallback. Minor waste: 'get next steps' is repeated as 'what to do next,' and 'Returns structured status data' is filler given an output schema exists.

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?

Output schema is present, so return values need no prose explanation, and the annotations cover the safety profile. With no parameters and a documented no-state fallback, an agent has everything needed to decide to call it and to interpret the result.

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?

Zero parameters, so there is no schema semantics to compensate for; baseline 4 applies. The description correctly implies a no-argument, state-inspection call rather than hinting at inputs that do not exist.

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?

Specific verb+resource: reports brand system progress and enumerates exactly what is surfaced (extracted colors/fonts/logo, confidence levels, session completion, next steps). An agent knows precisely what comes back. It does not, however, distinguish itself from similarly named siblings like brand_check, brand_report, or brand_preflight.

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 concrete triggers: resuming a previous session, checking readiness, or the user asking 'what's the state of my brand?', plus the no-.brand/ fallback case. Clear context for invocation, but no explicit exclusions telling the agent when a sibling such as brand_check is the better choice.

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