get_design_context

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

With no annotations, the description fully bears the burden of behavioral disclosure. It clearly states 'Read-only, no side effects,' and describes error behavior ('unknown/aliased categories return an actionable error'). This provides excellent transparency for safe invocation.

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 brief (5 sentences) with no wasted words. It front-loads the core purpose and safety, then concisely covers parameters, usage guidance, and alternatives. Every sentence 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?

Given no output schema, the description adequately describes the return value as a 'JSON summary' with specific elements. It covers all key aspects: purpose, parameters, behavior, and alternatives. While it does not detail the full output structure, it provides sufficient context for a tool with only 2 simple parameters.

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 input schema has 0% coverage, so the description must supply parameter meaning. It explains category's default behavior and lists valid values for tokenCategory with error handling. However, it does not mention that both parameters are required (schema does), and the values are implied but not formally enumerated in the schema. Overall, it adds substantial value beyond the bare 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 clearly states the tool's verb ('Get') and resource ('resolved design system context'), with a specific use case ('before building UI'). It distinguishes from sibling tools like get_token and get_component by noting they are for lookups by name, making the purpose distinct.

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 explicitly says 'Use this as the first call to understand what exists' and directs users to alternatives (get_token, get_component) for specific lookups. It could have also contrasted with get_conflicts or get_inferred_rules, but the guidance is clear and helpful.

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