get_document_tokens

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It says 'Extract', which implies a read-only operation, but it does not explicitly state that it does not modify the document, nor does it describe the return structure or any limitations (e.g., only local tokens, not remote). The disclosure is minimal and leaves important behavioral traits unstated.

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 a single concise sentence with the primary action front-loaded ('Extract active design tokens') and the enumeration in parentheses. Every word earns its place; there is no redundancy or filler.

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?

While it specifies the token types (paint, text, effect), it does not describe the return format (e.g., is it an array of objects? What fields per token?) or whether tokens beyond the listed types are excluded. Given no output schema, a bit more detail about the output structure would improve completeness, but the essential purpose is clear for a simple extraction 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 tool has zero parameters, so there is no parameter schema to enrich. According to the rubric, a parameter-free tool gets a baseline of 4. The description clarifies the scope of the output (token types), which indirectly helps an agent know what to expect, fully meeting the expectation for tools without parameters.

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 uses the specific verb 'Extract' with resource 'active design tokens from the document' and enumerates the token types (paint, text, effect), which clearly distinguishes it from sibling tools like 'get_document_info' or 'get_selection'. A generic alternative would be 'Retrieve tokens', but this is precise and informative.

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?

No guidance on when to use this tool versus alternatives, and no mention of scenarios where it is preferred. It simply states the function without contextual usage cues (e.g., 'Use when you need design tokens before editing styles'), so an agent has to infer the appropriate call context from the purpose alone.

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