Get the whole brand as one document

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

No annotations are provided, so the description carries the full burden. It discloses read-only behavior ('read-only, mints no version, writes nothing'), required scopes ('kits:read'), owner-scoping, conflict-resolution rules, and specific non-error outcomes. This gives agents a strong behavioral model without needing external annotation signals.

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 value proposition and uses a single dense paragraph. Every sentence conveys meaningful information, but the length is slightly over-verbose for an agent-facing description, with phrases like 'which is the honest answer and not an error' adding nuance but not essential structure.

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?

Despite no output schema and no annotations, the description is remarkably complete. It explains what the returned document contains, how conflicts are resolved, what happens in edge cases, error conditions (409), auth requirements, and side effects. This is a fully specified behavior description for a complex 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?

The schema covers the single parameter projectId with a description ('Owned brand project id from list_brand_projects'), and schema coverage is 100%. The description adds owner-scoping context, but this is already implied by 'Owned' in the schema and is more of an access requirement than a parameter semantic. Thus, the baseline of 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?

The description clearly states the tool's purpose: returning the brand as one ready-to-build document, specifically the kit's DESIGN.md with pinned layers written in. It distinguishes itself from sibling tools by explicitly naming get_design_md, get_image_direction, get_interface_style, and get_page_recipe and explaining why using them separately is inferior.

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 provides explicit when-to-use guidance: 'Use this instead of assembling get_design_md plus get_image_direction plus get_interface_style plus get_page_recipe yourself.' It also covers edge cases—no pinned layers returns the kit's DESIGN.md, a locked layer is named with an upgrade path, and no chosen kit returns 409—so agents know when the tool is appropriate and what to expect.

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