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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the burden and does so richly: it enumerates the default return shape, the extra measured fields for deep-decoded products, normalization ('All hex normalized'), and that data is 'measured from the live page, not guessed'. It also discloses the astryx build workflow.

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 and usage, then return values, then the format option — a logical order with no filler sentences. It is fairly long and the format paragraph is dense, but every sentence conveys distinct operational 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 no output schema, the description fully compensates by describing the returned token groups, the deep-decoded extras, and the alternate text outputs per format. An agent has everything needed to call it and 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?

Schema coverage is 0%, so the description must compensate, and it does for 'format' by spelling out empty, 'all', and each named format ('tailwind', 'css', 'design_md', 'tokens', 'astryx') with what each returns. The 'site' parameter is only conveyed by example ('site="Linear"'), which is adequate but less explicit than the format documentation.

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 ('Get a product's full, LLM-verified design system') and states the goal ('match its exact look'). It clearly differentiates itself from siblings like list_my_design_systems and generate_asset by naming them in their proper roles.

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 trigger phrase ('Use this for "design like <product>"') with concrete examples (Linear, Stripe, Figma). It also explains resolution order ('Your own private BYODS design systems ... resolve first') and points to the downstream call generate_asset(style_from=...) for icon matching.

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