RelayShield Scam Checks

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

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered; the description goes well beyond that. It discloses the zero-count interpretation caveat, the return shape (breach count plus named sources), and an important failure mode (missing RELAYSHIELD_API_KEY returns setup instructions instead of calling the API).

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 tight sentences: what it does, how to call it, and what comes back. The key caveat (zero ≠ safe) is placed early and every sentence carries distinct 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 compensates by describing the return value (count plus named sources) and the setup-instructions fallback when the API key is absent. For a one-parameter read-only lookup, nothing an agent needs to call it correctly is 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% for the single email parameter, including case-insensitivity, so the description's 'Provide email' adds nothing over the schema. Baseline 3 is appropriate when the schema fully documents the parameter.

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: checks an email address against known data breaches. The resource is distinct from the sibling tools (check_link, check_wallet), but the description never names those alternatives, so the differentiation is left to inference rather than made explicit.

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 supplies a genuinely useful interpretive rule ('a count of zero means no breaches were found in the corpus, not that the address is safe') and the API-key prerequisite, but gives no explicit when-to-use-this-vs-check_email guidance or any exclusion criteria. Usage is implied rather than directed.

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, non-destructive), so the bar is lower; the description still adds useful behavior: the return shape (risk level, score, specific flags), the 'unknown means nothing conclusive' semantic, and the explicit guarantee that it never reports an email as safe. This 'never says safe' caveat is exactly the kind of nuance an agent needs and cannot get from 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?

Three sentences, front-loaded with the purpose, then inputs, then return semantics. Tight overall, though the mid-sentence param enumeration partially duplicates the schema and could be trimmed.

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 return-value burden itself and does so: it explains the risk level, score, flags, the 'unknown' verdict, and the no-safe-verdict guarantee. All seven optional parameters are schema-documented, so nothing needed to call the tool is 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%, so every parameter is already documented, and the baseline is 3. The description only re-enumerates the field names plus the 'up to 25' link cap that the schema already states via maxItems, adding no new syntax or format meaning.

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 ('scores') and resource ('a suspicious email for phishing signals') and names the input surface. It is clearly distinguishable from siblings check_breach, check_link, and check_wallet, which operate on different artifacts.

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 phrase 'Provide any of' communicates that inputs are flexible and nothing is required, which is implied usage guidance. However, it never says when to reach for check_email versus check_link, even though link analysis is a documented sub-behavior here, so routing between siblings 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?

Beyond the read-only/non-destructive annotations, it discloses the batch ceiling, the verdict vocabulary (FLAGGED or unknown), the returned counts, and critically the semantics that 'unknown' means nothing is known and the tool 'never reports a link as safe' — preventing an agent from misreading a non-flag as a clean bill of health.

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?

Four sentences, front-loaded with the purpose, and every sentence carries useful content. The 'Provide either url or urls' instruction slightly repeats the earlier 'one URL, or up to 25 URLs' framing, a small redundancy that costs it a point.

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 return-value burden and does so: per-link verdicts with reasons plus checked/flagged/incomplete counts. For a two-parameter read-only checker, nothing an agent needs to call or interpret it is 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 both parameters including 'Omit when sending url/urls' and maxItems 25, so the baseline is 3. The description largely restates those same constraints rather than adding new parameter semantics.

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 (checks URLs against RelayShield's threat-intelligence corpus for phishing, malware, and scam abuse) and scopes the input shape (one URL or up to 25). The URL-centric scope cleanly distinguishes it from the siblings check_breach, check_email, and check_wallet.

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 tells the agent how to invoke it ('Provide either `url` ... or `urls`'), making the mutual exclusivity of the two parameters clear. It gives no explicit when-not-to-use guidance or routing advice relative to the sibling checkers, but the resource boundary is unambiguous enough that the gap is minor.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description goes beyond them with the non-obvious caveat that an 'unknown' verdict means nothing is known against the address and is NOT a safety assertion — a genuinely useful interpretive rule.

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?

Four tight sentences, front-loaded with the operation and its read-only nature, then input handling, then return vocabulary, then the critical 'unknown' caveat. Every sentence carries distinct information with no filler.

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?

There is no output schema, so the description must carry return-value semantics — and it does, enumerating the risk levels (CRITICAL/HIGH/MEDIUM/LOW/unknown) and the underlying sanction, scam, drainer, and phishing flags. Nothing an agent needs to call or interpret this tool is 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?

There is one parameter with 100% schema description coverage, so the schema already documents `address` and auto-detection. The description restates the auto-detection behavior but adds no format or validation detail beyond the schema, matching the baseline-3 case for high coverage.

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 — a read-only risk assessment of a cryptocurrency wallet address — and immediately scopes what it does not do (never moves funds). The wallet-screening resource is clearly distinct from the sibling check_email, check_link, and check_breach tools.

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?

Tells the agent how to invoke it (provide `address`, chain is auto-detected) and clarifies the read-only nature, which sets expectations for use. It does not name when to prefer a sibling or state exclusion conditions, but the siblings target entirely different resources so the distinction is self-evident.

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