Scanverity Resolution Rules

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses rate-limit behavior ('Uses one API call; honor recommended polling interval and Retry-After'), billing semantics (preserve billable/metering values, don't assume payment), status handling (released vs withheld/failed), and a security note on untrusted returned text. This is substantial behavioral context the annotations cannot convey.

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 the usage trigger, then packs billing, polling, status, and security constraints into a compact set of sentences that each carry information. Slightly dense and run-on, but there is little wasted text.

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 and a rich procedural tool, the description still conveys status semantics (released/withheld/failed) and billing values, and annotations cover the safety profile. It is nearly complete, though the returned assessment's overall structure is only lightly sketched.

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?

Only one parameter exists with 0% schema description coverage, but the schema pattern ('^ra_[a-f0-9]{32}$') supplies the format. The description calls it a 'saved assessment ID' but adds no format, sourcing, or lookup guidance beyond that, so it compensates only partially for the coverage 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 ('Read one saved assessment ID') and explicitly disambiguates from the creating sibling with 'no new report is created.' An agent can distinguish it from scanverity_request_assessment without opening either schema.

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 clear trigger conditions: 'after requesting Scanverity research' and 'when the user asks for an existing report or its progress,' which implicitly routes to scanverity_request_assessment for new work. It stops short of explicitly naming the alternative tool as the low-cost path, so it falls just below full marks.

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 the read-only, non-destructive, closed-world profile, and the description still adds substantive behavior: no assessment or charge is created, the limits are per-process and reset on restart rather than being remaining purchased quota, account-level limits still apply, and request keys count attempted unique operations including rejected ones but not reports or charges. That is genuinely non-obvious operational context an agent could not infer from the annotations.

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 content is front-loaded on usage, which is reasonable, but the text is a dense run-on with redundancy: 'does not order or charge' and 'No assessment or charge is created' say the same thing twice, and 'Account limits still apply' dangles without a referent. Several sentences could be tightened without losing information.

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 convey what comes back, and it largely does by listing the topics returned (permissions, environment, limits, pricing/quote paths). It does not describe the response shape or how the limit counters are presented, which is a minor gap for a zero-parameter informational 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 takes zero parameters and the schema is empty, so there is no parameter semantics to clarify; baseline for a no-parameter tool is 4. Nothing in the description is needed or missing on this dimension.

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 enumerates the concrete resources it reports on (connection permissions, Live vs Sandbox, local request limits, pricing links, quote paths, paid-report requirements), so the agent knows exactly what this returns. It never names its siblings, but the repeated 'does not order or charge' / 'No assessment or charge is created' implicitly separates it from scanverity_request_assessment.

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?

'Use this when checking...' gives an explicit, itemized trigger list covering the main reasons an agent would call it. There is no explicit when-not statement or named alternative, but the negative scoping ('does not order or charge') steers the agent away from the ordering siblings.

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 declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds meaningful behavioral context beyond those fields: it explicitly does not create an account/order/report/charge and clarifies 'a quote request and an MCP connection are not purchases.' That is real value not present in the annotations.

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-loaded with the trigger condition and dense with concrete price points, with almost no filler. However it is essentially one very long run-on sentence that would be easier to parse as a short list of the price paths.

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 rightly explains what is returned (the specific quote paths and API availability), and annotations cover the safety profile, so an agent can call it confidently. It stops short of describing the response's shape or fields, which is a minor residual gap.

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 takes zero parameters, so the baseline of 4 applies; there is nothing for the description to document beyond confirming it is a no-argument lookup.

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 resource (Scanverity pricing, products, ordering paths) and enumerates what it returns, so the agent knows exactly what comes back. It implicitly distinguishes from request_assessment via the 'does not create an account, order, report, invoice or charge' clause but never names the sibling tools explicitly.

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 clear triggering conditions ('Use this public tool when a user asks about Scanverity prices, products, access...or what to do without an approved customer account'), which is strong when-to-use guidance. It does not name alternative siblings (e.g. request_assessment) for when the user actually wants to order, leaving that routing implicit.

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 declare destructiveHint=true and idempotentHint=false, but the description supplies the missing behavioral context: it can consume paid allowance (with evaluation/Sandbox excluded), requires an authorized account with existing allowance, retry semantics keyed to the same operation_key within 30 days, no automatic polling/payment/trade/activation, and returned market text must be treated as untrusted data. This goes well beyond what the annotations convey.

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-loaded with the primary trigger, then routing, then cost/authorization, then retry semantics, then return handling. Dense and every sentence carries a distinct constraint, though the run of short declarative clauses reads slightly list-like rather than flowing.

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 still tells the agent the call returns an assessment ID that must be read separately (routing to scanverity_get_assessment), plus cost, auth, retry, and safety caveats. An agent has everything needed to invoke it correctly and handle the result.

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 a constraint not in the schema: reuse the operation key AND market within 30 days for a permitted retry, and do not regenerate a key after a timeout. That materially clarifies the intended use of operation_key beyond its schema text.

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: requesting source-linked research on what makes a Polymarket contract settle Yes/No, enumerating the dimensions covered (resolution criteria, deadlines, ambiguous wording, dispute risk, forecast match). It also names the sibling scanverity_search_markets and the follow-up scanverity_get_assessment, so an agent can separate it from siblings 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 trigger conditions ('when the user wants source-linked evidence about...'), a routing rule for missing inputs ('If no exact contract is known, use scanverity_search_markets first'), and clear exclusions ('never submit a broad topic or choose an unstated deadline'). Alternatives and when-not-to-use are both present.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial behavioral context beyond them: degraded-mode behavior when the global registry is unavailable (limited result_scope, no outcomes), the warning that an empty subset never proves absence, and the account-free sibling fallback. It also discloses the cost/billing profile ('no report, payment or report-allowance consumption').

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-loaded with the use case, then return shape, then fallbacks and exclusions. Dense but each sentence carries distinct information. Slightly over-long: the 'verify the exact contract' line and some caveat repetition could be trimmed without losing meaning.

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 correctly supplies the return shape (contract IDs, questions, deadlines, source links, conditional outcomes) as well as degraded-registry behavior, pagination/absence pitfalls, and the authorization fallback path. Nothing an agent needs to call this correctly appears missing.

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 100% and the schema already documents query format, limit bounds, date patterns and cursor semantics in detail. The description reinforces the query intent ('short topic keyword, usually in English') and the cursor/absence caveat, but largely restates what the schema provides, so the baseline 3 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?

States a specific verb+resource pair (search prediction markets) and immediately scopes the domain (politics, elections, ceasefire, economics, crypto, sport). It also enumerates what comes back (Polymarket contract IDs, questions, deadlines, source links), so an agent can distinguish it from siblings like scanverity_get_assessment or scanverity_offers without opening a schema.

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?

Explicit trigger conditions ('when a user asks about prediction markets... even without naming Scanverity or providing a URL') plus explicit exclusions ('Not general news search, live odds, a probability forecast or a trading recommendation'). It also routes to the correct sibling when authorization is unavailable (scanverity_offers) and warns against guessing market IDs.

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