get_token_map

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

No annotations exist, so the description carries the full burden of behavioral disclosure. It thoroughly explains the two runtime modes: without 'path' it returns the full map with all top-level keys, and with 'path' it returns the resolution details for that single path. It also discloses the dependency requirement ('css-is-awesome >= 1.19.0') and the absence of side effects by framing it as data. This is comprehensive behavioral transparency.

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?

Every sentence earns its place: identity, conditional output shape, use case, and dependency. The key distinction ('as data') is front-loaded, and the detailed shape information is dense but relevant. There is no filler or repetition.

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?

There is no output schema, so the description correctly assumes responsibility for return values; it lists the exact fields for both the full-map and single-path responses. It also covers the prerequisite version requirement and the relationship to theme_from_tokens. Nothing an agent needs to invoke this correctly is missing.

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 'path' parameter at 100%, and the description provides additional meaning beyond that: a concrete example ('color.text.primary'), clarification that omitting it returns the whole map, and a mapping of each usage mode to its output shape. This meaningfully enriches the parameter semantics.

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 opens with a precise subject: 'The design-token → cia-token mapping that theme_from_tokens applies, as data.' It clearly identifies the resource (a mapping as data), distinguishes it from the converter tool by emphasizing 'as data,' and states concrete use cases: 'map a Figma / DTCG / Tokens Studio token name to the cia custom property' or 'check a name before building a theme.' The purpose is specific and non-tautological.

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 when to use it: to translate token names the same way the converter does, or to validate a name before building a theme. It implicitly differentiates from theme_from_tokens by positioning itself as the underlying mapping rather than the applying operation. It does not explicitly name alternatives or exclusion conditions, but the intended context is unambiguous.

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