backgrounds

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds a substantial output contract: the style card contents and the JSON Schema for generate requests. Since there is no output schema, this return-value transparency is valuable, though error behavior is not discussed.

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?

Two sentences carry the full message with a front-loaded core deliverable. The colon-delimited list in the first sentence packs useful detail without padding, and the second sentence adds the JSON Schema behavior without any 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?

For a read-only lookup operation with two parameters, one required, and no output schema, the description is complete. It explains what the result contains, how format affects the response, and what the name refers to. The sibling-routing nuance is a usage-guidance issue rather than a completeness gap.

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%: 'name' identifies the structure and its source, and 'format' documents the enum, default, and best use for each value. The description itself adds little about the tool's own parameters beyond noting that JSON Schema is returned, so the baseline of 3 applies.

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 deliverable: a full style card for one structure, covering appearance, mood, text placement, tips, and parameter ranges/defaults/effects. It also returns the JSON Schema for a generate request. This clearly distinguishes it from siblings like list_backgrounds (listing structures) and generate_background (creating a background).

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 description gives clear context: it is meant for inspecting a single known structure, and the returned JSON Schema is explicitly tied to a generate request, which implies use before generation. It does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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?

Adds substantial context beyond the annotations: determinism ('same structure, options and seed always give the same image'), the instruction to store the returned seed, and the caching/permanence semantics of the returned URL. These details align with and enrich the readOnlyHint and idempotentHint annotations without contradicting them.

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 dense sentences with zero filler. Every clause carries information: output formats, determinism, return contract, and the prerequisite sibling call. The most decision-relevant facts are front-loaded.

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?

Given 9 parameters, nested objects, and no output schema, the description covers the critical unknowns: what the tool returns, determinism behavior, and where to get shape/options details. It does not describe error cases or behavior for unknown structure names, but for selection and initial invocation this is adequately complete.

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?

At 67% schema coverage the schema does much of the work, but the description adds real meaning where it matters most: it explains the seed's role in determinism ('store the returned seed') and routes the agent to describe_background for the opaque, structure-specific shape object. This compensates for the least-documented parameters.

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 ('Render') plus resource ('background') and the two output formats (SVG/PNG). It also names the return contract (permanent URL + inline preview), which distinguishes it clearly from the describe/list/suggest siblings.

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 precondition and sibling pointer: 'Call describe_background first to learn which shape options the structure honours.' This tells the agent the correct workflow before invoking. It lacks explicit when-not-to conditions against list_backgrounds or suggest_backgrounds, but the core usage context is clear.

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 safety with readOnlyHint and idempotentHint. The description adds useful behavior beyond that: it supports filtering by query, tag, or mood, and specifies the return shape (name, summary, mood, use cases, preview URL), which is valuable since no output schema exists. No contradiction with annotations.

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?

Two sentences with no filler: purpose is front-loaded, optional filters are summarized in a compact list, and return fields are enumerated. Every phrase earns its place.

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, all-optional-parameter list tool with no output schema, the description covers purpose, filters, and return content sufficiently for an agent to make a correct call. Minor gaps like pagination behavior and limit defaults are not blocking given the simple catalog-browsing context.

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 schema documents mood and query but not tag or limit, leaving 50% coverage. The description adds that tag and mood serve as filters, which helps clarify tag, but it does not explain the limit parameter or the acceptable tag values. It partially compensates for the schema gap but not fully.

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 has a specific verb and resource: 'Browse the catalog of background structures.' It also enumerates the returned fields. It is naturally distinct from describe/generate siblings, but it does not explicitly differentiate from suggest_backgrounds, so it falls short of a 5.

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 purpose is implied through 'browse the catalog' and the optional filtering flags, but there is no explicit guidance on when to use this tool versus describe_background or suggest_backgrounds. No exclusions or alternative routing are provided, leaving some selection 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds account scoping ('on this account') and the fact that results contain slugs usable as `brand` values, which is useful behavioral context beyond the annotations.

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?

Two sentences with no waste: the first states what the tool returns, and the second explains how to use a returned value. The most important information is front-loaded.

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, read-only list tool, the description is sufficiently complete: it names the resources, scopes them to the account, and shows how results are consumed downstream. It does not describe the exact response shape, but the simplicity of the tool makes that a minor gap.

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 has zero parameters, so parameter semantics is not a burden on the description. The description still meaningfully mentions the `brand` slug concept, which clarifies how the output relates to another tool's parameter.

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 title 'List brand kits' and description 'Saved brand palettes on this account' clearly identify a read/list operation over brand kit resources. It does not explicitly distinguish itself from list_palettes, but its relationship to generate_background via slug usage adds specificity.

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 description gives concrete downstream usage: pass a kit's slug as `brand` to generate_background to render on-brand without repeating hex colors. It implies this tool is useful for fetching those slugs but does not explicitly mention when to use list_brand_kits instead of list_palettes or other siblings.

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 read-only, idempotent, and non-open-world behavior, so the bar is lower. The description adds useful context: palettes are built-in and curated, the response contains hex colours and derived mood tags, and the output id feeds generate_background. No contradiction with annotations.

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?

Two sentences, each earning its place: the first defines the resource and its contents, the second explains how to use the result. No redundant wording or 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?

For a simple optional-filter list tool with read-only/idempotent annotations and no output schema, the description tells the agent what to expect (palettes with hex, mood tags) and how to consume the result (id mapping). This is sufficient for correct invocation.

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 schema already documents the optional mood parameter with examples, giving 100% coverage, so the baseline is 3. The description adds a few more mood tag examples and notes they are derived, but this is marginal enrichment rather than essential meaning.

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 clearly states the tool lists 'built-in curated colour palettes' with hex colours and derived mood tags, using a specific verb and resource. It also distinguishes the scope from background-oriented siblings by focusing on palettes and explicitly pointing to generate_background.

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 phrase 'Pass the id as palette.palette to generate_background' gives a clear downstream workflow, showing when this tool is useful. It does not name sibling alternatives or state when not to use it, but the intended context is clear.

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 read-only and idempotent behavior, and the description adds useful output behavior: it returns why each match occurred, matching built-in palettes, and an example request for generate_background. This goes beyond the annotations without contradicting them.

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 entire description is one front-loaded sentence that covers purpose, input style, return contents, and a pointer to generate_background. There is no filler or redundant repetition of the title or 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?

With no output schema, the description appropriately lists the returned elements: why each matched, matching built-in palettes, and an example request. The only notable omission is any guidance on the 'limit' parameter, but the parameter name and schema constraints largely speak for themselves.

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 0%, so the description must add meaning. It provides a concrete example of what a natural-language 'brief' looks like, but it does not mention the 'limit' parameter at all. The brief semantics are improved, but limit remains only structurally defined.

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 clearly states the tool's verb and resource: 'Rank structures for a natural-language brief' and explains what it returns. It is distinguishable from siblings like generate_background and list_backgrounds because it emphasizes ranking and producing a ready-to-run generate_background example, though it does not explicitly contrast itself with those siblings.

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 description gives clear context: this tool is for natural-language briefs and returns ranked suggestions rather than a single generated artifact. It does not explicitly say when not to use it or name alternative tools, but the example and output framing imply the appropriate use case.

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