Synthesize a portal theme from brand preferences

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

The description goes beyond annotations by explaining side effects: it fetches the website (SSRF-guarded) only to suggest colors, and it explicitly states it does not create anything. This aligns with the readOnlyHint and provides transparency about the fetch operation and the purpose of generating a spec. It also clarifies the relationship with create_resource without overstepping.

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 overly verbose. It includes a full example of a create_resource call, mentions VC-tracked content write, and references the design_intake PROMPT—details that are not necessary for understanding the tool's core function. The first sentence is clear, but the subsequent expansion dilutes the message and could confuse an agent.

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?

The description covers the main workflow (fetch, suggest, generate spec, then create) and clarifies that the output is a spec for use with create_resource. It also notes the SSRF guard. However, it does not mention the output format or how the spec is returned, which could be a gap for agents that need to consume the result. Still, given the schema covers params, the description is largely 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?

While the schema already documents each parameter thoroughly (100% coverage), the description adds meaningful relationships: it explains that website_url is fetched only when primary_color is omitted, and that brand_name is used to name the theme. However, it does not elaborate on all params (e.g., font, mode), but the schema descriptions already handle those, so the additional context is beneficial.

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 function: 'Turn brand preferences into a portal theme spec' and explicitly notes it does not create anything. This is a specific verb-noun pair that distinguishes it from a creation tool, and the no-write intent is reinforced by the readOnlyHint annotation.

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 implies a workflow (fetch site, suggest colors, then create via create_resource) but does not explicitly state when to use this tool versus alternatives. It mentions the design_intake PROMPT but does not provide clear conditions or scenarios for invocation. More explicit guidance such as 'use this when you need to generate a theme spec' would improve clarity.

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