VAREXIS-INDEX - Source-linked evidence

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: matching ignores case/punctuation/common words, it does not validate new claims, no-match is not a negative verdict, and it returns up to 20 results. These are non-obvious traits an agent needs for correct interpretation.

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?

Front-loads purpose and the sibling-routing rule, then parameters, then return shape and caveats. Every sentence carries distinct information; no filler despite the length.

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 adequately describes the return (route_id, matched wording, scoped question; ~20 matches) and the downstream preview path. It covers purpose, routing, parameters, result shape, and matching caveats for a read-only search 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?

Schema coverage is 100%, so baseline is 3, but the description adds useful semantics beyond the schema: 160-character max on query, offset maximum 10000 with a +20 page-increment convention, and the browse behavior when query is blank. It reinforces rather than merely restates.

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?

States a specific verb+resource ('Search existing reviewed evidence questions and fixed-pack topics') with clear scope ('when you do not know a route ID'). Explicitly names the sibling tool find_package_advisories for the contrasting case, so an agent can pick correctly without opening schemas.

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?

Gives explicit when-to-use (governance, tool permissions, audit/export, evidence-boundary questions; unknown route ID), when-not ('For a known software advisory ID or an exact ecosystem/package lookup, use find_package_advisories'), and a downstream step (pass route_id to preview_evidence_answer). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/destructive=false, but the description adds substantial context beyond them: a 20-result cap, explicit source capture dates and withdrawals, EPSS/KEV preview content, fix boundaries, and the critical caveat that no results never mean safe.

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?

Core purpose and parameter rules are front-loaded, followed by return behavior and caveats, so nothing is buried. It is dense and clause-heavy, and 'Free and read-only' partially restates the annotations, but nearly every sentence earns its place.

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 must describe returns, and it does so thoroughly: match count, route IDs, capture dates, withdrawals, preview composition, and score caveats. An agent has enough to call it and interpret the output.

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 load, and it does: it defines the advisory_id-or-ecosystem+package combination rule and explains cursor as continuing the same lookup. It omits format/length details, but the usage relationships are the meaningful part.

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 names a specific verb (look up) and resource (known advisory ID/alias, or ecosystem + package name) within a scoped collection (frozen OSV). It is readily distinguishable from siblings because it explicitly routes results to preview_evidence_answer.

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 gives a clear input rule ('Supply advisory_id OR both ecosystem and package') and states cursor's continuation role, plus explicit exclusions ('No range solving, current scanning, independent verification or payment'). It does not explicitly contrast with find_evidence_questions, so it stops short of full alternative routing.

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

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

Annotations already establish this as a safe read, but the description adds substantial non-obvious behavior: it cannot charge or retrieve purchases, no keys should be sent, free evidence needs no payment, existing subscriptions exclude the four standalone licences, and compatible agents need owner spending authority. That is meaningful disclosure well beyond the structured hints.

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 purpose is front-loaded, but the middle sentences pack a lot of pricing and contract minutiae (GBP49, GBP79, agent_payments_contract, recovery) into one dense block. Much of this is useful, but the single-breath length reduces scannability.

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 input parameters and no output schema, the description compensates reasonably by enumerating what the response contains (availability, prices ex-VAT, requirements, contracts). An agent has enough to call it and interpret the result, though return-value specifics remain prose-only.

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?

There are zero parameters, so the baseline is 4. The description correctly signals the empty call ('Call with {}') and does not invent faux parameter semantics, which is appropriate.

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 states the resource precisely (access and licensing options: paid saved retrieval, unsigned receipts, executable licences) and what it returns (live availability, GBP prices, product requirements, payment contracts). It is distinguishable from the free-preview sibling, though it lacks a crisp single verb and leans on enumerating return contents.

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 says to call it 'after a free preview' and points to purchase_url for hosted checkout, giving a clear sequencing condition and routing to a follow-up action. It stops short of naming sibling tools outright, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: cost (free), return contents (cited evidence, review dates, limitations, snapshot_sha256), and deliberate preview truncation (scope, interface summaries, representative findings; no exact operational schemas or licensed ZIP). The preview_payload_sha256 distinction and the 'no live testing' caveat are exactly the behavioral details annotations cannot express.

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 most decision-critical facts (what it previews, where route_id comes from, that it's free) are front-loaded, and there is little waste. It is a dense single block, though, and the preview-scope and version caveats could be separated for faster scanning.

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?

No output schema exists, so the description must describe returns, and it does (cited evidence, review dates, limitations, snapshot_sha256, differing hashes per product type). Combined with annotations covering the safety profile, an agent has everything needed to call this correctly and interpret what comes back.

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 carries the burden, and it does explain both parameters: route_id's provenance and version's restriction to exact advisory-listed versions rather than ranges. It stops short of stating format or the fact that version is optional-and-exact-only in a fully explicit way, leaving a small gap.

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?

States a specific verb and resource ('Preview a published answer or pack') and immediately identifies the source of the required identifier ('route_id from find_evidence_questions or find_package_advisories'). This distinguishes it cleanly from all three siblings, which are finders or a pricing tool.

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 routes the agent: 'For prices and licences, call get_index_access_options', and defines the version filter's scope ('exact advisory-listed versions only, not ranges or safety'). It also declares the boundaries ('Free', 'No paid saving or live testing'), so when-to-use and when-not-to-use are both covered.

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