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

Despite annotations covering safety (readOnly=false, idempotent=true, destructive=false), the description adds critical economics the annotations cannot express: unlocking costs 19,000 credits once per account, and an already-unlocked dossier costs 0. It also discloses the workspace-key requirement and mandates user confirmation before spending, which is exactly the context an agent needs before invoking a costly non-read-only call.

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?

Three front-loaded sentences with zero filler: what you get, what it requires, what it costs. The cost and confirmation warning are placed where they will be read before the call, not buried.

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?

An output schema exists, so return values need not be explained, and the description covers auth, cost, and user-consent behavior. It stops short of stating what occurs when credits are insufficient or when the underlying gap is not found, minor gaps for an otherwise well-covered definition.

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 description coverage is 0%, so the description must carry the parameter meaning. It implies the single 'id' refers to a scored gap, which is useful, but it doesn't state the id format, where to obtain it (e.g., from list_gaps or get_gap), or what happens if an unscored id is passed.

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 gives a specific resource (a full dossier for a scored gap) and enumerates its contents: product-by-product checks, live closest products, supplier candidates, and a suggested spec. It is clear what the tool returns, but it never explicitly contrasts itself with the sibling get_gap, so the agent must infer that get_gap is the lighter-weight read and this is the expensive deep-dive.

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?

It states a prerequisite (needs a workspace key) and a procedural rule (ask the user before unlocking), which is real usage guidance. However, it gives no explicit when-to-use-this-vs-alternatives rule against get_gap, list_gaps, or check_demand, leaving the cost-driven selection to inference.

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