Symbol Exists (free, keyless)

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

Beyond the readOnly/idempotent annotations, the description discloses the static analysis ceiling (cannot detect runtime-created symbols), free-tier rate limits (25 calls/day shared across attester_* tools), quota fallback to a paid route, and a detailed output structure including proof/attestation fields. This adds substantial behavioral context.

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 uses labeled sections (WHAT/WHEN/WHEN NOT/COST/OUTPUT) to pack information into a scannable format. Every sentence carries distinct information—no filler—making the length justified.

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?

For a read-only lookup tool with a full output schema, the description covers purpose, usage, limitations, cost, and output fields. It is self-contained and leaves no major questions about how to invoke or interpret results.

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 covers 100% of parameters with descriptions. The tool description adds that 'symbol' refers to functions, classes, and constants and reinforces the 'latest indexed version' default for the version parameter, slightly enriching the schema. Baseline 3 plus one for the semantic clarification.

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 'WHAT: checks whether a symbol (function, class, constant) exists in a package at the latest indexed version' — a specific verb and resource with clear scope. It also mentions closest-match suggestions, distinguishing it from sibling tools like package_exists and symbol_signature.

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?

Explicitly provides 'WHEN' (before calling an API you are not sure exists) and 'WHEN NOT' (dynamically created symbols), offering clear usage guidance. However, it does not name alternative tools directly, so it stops short of a full 5 on the alternatives criterion.

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