xquik

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

Beyond the annotations (destructiveHint, openWorldHint, etc.), the description discloses a rich set of behaviors: bounded sandbox, no filesystem/network access, automatic auth injection, requirement for prior user confirmation on mutations, pagination semantics (`has_more`, `next_cursor`), and detailed error handling (402, 429, 404). It also explains the package-stub fallback behavior. This far exceeds what annotations provide.

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 long but well-structured with clear headings and front-loaded purpose. Each section serves a distinct function: usage, safety, behavior, errors, format, examples. While some repetition exists (e.g., auth injection mentioned in multiple places), the organization makes it easy to scan and the content earns its place for a tool with 120 routes and safety implications.

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 carries the burden of explaining return behavior and errors. It covers pagination, durable actions, retry guidance (`safe_to_retry`, `next_action`), both live and stub modes, and safety prerequisites. Given the complexity and range of operations, this description is remarkably complete for effective agent usage.

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 100%, so the baseline is 3, but the description adds meaning by explaining the `xquik.request(path, options?)` format, showing multiple examples (search, user lookup, POST), and describing the `cursor` parameter for pagination. The schema's parameter description is good, but the tool description reinforces and extends it with practical usage patterns.

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 'Live Xquik tool: send confirmed requests across 120 catalog routes' and distinguishes from the package stub. It names specific operations (tweet search, user lookup, etc.) and explicitly contrasts with the sibling 'explore' tool, leaving no ambiguity about what this tool does.

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 includes dedicated 'When to use' and 'When NOT to use' sections. It explicitly says to use after calling 'explore' and tells agents to NOT use it for endpoint discovery, pointing to 'explore' as the alternative. This is explicit, actionable guidance.

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