Tanod Security

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

With no annotations provided, the description carries the full burden and does so: price (USD 0.005), free quota (3 scans or 30 checks per IP per UTC day, shared pool), latency (under 1 s, p95 ~1 s, max ~4 s), 10-minute caching, and failure handling ('if the chain cannot be read the call fails and is not charged'). It also names the return fields and verdict taxonomy, which no structured field supplies.

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 purpose and trigger, then packs cost, limits, latency, and caveats into dense but useful clauses. Every sentence earns its place for an agent making a paid call, though the middle section is heavy and could be broken into shorter units.

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?

Though there is no output schema, the description enumerates the return shape (verdict, risk_score 0-100, plain-language reasons, proxy/token/verification details, block height) and discloses cost, quota, latency, and failure semantics. Nothing needed to decide whether and how to call 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 both parameters are already documented with titles, an enum for chain, and the 0x+40-hex pattern. The description's restatement of address format and chain values adds no meaning beyond the schema, so the baseline 3 applies.

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 ('pre-transaction risk check' on an address) with concrete scope: send, approve, or buy a token on Base or Ethereum. It is clearly not a source-code or package scanner, but it never explicitly contrasts itself with the sibling scan_contract_address, which an agent could easily confuse with this 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?

Gives a crisp trigger ('call it right before you send a transaction to, approve, or buy a token') plus explicit exclusions: no honeypot simulation, no liquidity/oracle analysis, and a low verdict is not a clearance. No named alternative tools or routing rules to siblings are provided, so it stops short of a 5.

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 annotations (readOnly/idempotent/non-destructive/openWorld), it discloses case-sensitivity rules per address format, latency ('under 0.1 s, first call up to 1 s'), price (USD 0.002), a shared free-tier pool, and the disclaimer/list_date semantics. This is exactly the extra 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?

Purpose is front-loaded and the dense detail (formats, return fields, limits, pricing, disclaimer) is largely information-bearing. It is long and reads as a wall of text, but almost every clause earns its place for a paid, caveat-heavy screening tool.

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 enumerates the return fields (matched, matches with sdn_uid/sdn_name/etc., list, list_date, list_addresses, source, disclaimer) and covers scope, caveats, cost, and latency. Nothing an agent needs to invoke 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 coverage is 100% and there is a single parameter, so the schema already carries the format. The description still adds value by explaining the case-sensitivity distinction between EVM/bech32 (case-insensitive) and base58 BTC/TRX (exact match), which the schema does not state.

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 a specific verb and resource ('screen one crypto address against the US OFAC SDN list's digital currency addresses'), naming the exact list and scope. The word 'one' implicitly distinguishes it from the sibling check_sanctions_batch, so an agent can tell them apart.

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 rich usage context: scope limits (OFAC SDN crypto addresses only, no other lists, no clustering/ownership/exposure analysis), the caveat that a non-match does not clear an address, and verification guidance. However, it never explicitly names check_sanctions_batch as the alternative for multiple addresses, 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive) and the description still adds rich operational context beyond them: 1 kB body fetch cap, final-response-after-redirects grading, max 4 redirects each re-checked, ports 80/443 only, 422 on refused targets (not charged), per-target-host rate limit, and 0.3-2 s timing. This is exactly the extra context annotations cannot carry.

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?

Purpose is front-loaded and most clauses are load-bearing (returns, redirects, refusals, limits). The pricing and free-tier-pool enumeration is somewhat long relative to the single-parameter operation, but it is decision-relevant for cost-aware agents, so the length is mostly 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?

There is no output schema, yet the description fully explains the return shape: `score` 0-100, `grade` A-F, every `deduction` with reason, redirect chain, and `upgraded_to_https`. Combined with fetch constraints, rate limits, and pricing, an agent has everything needed to call and interpret the 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?

Only one parameter with 100% schema description coverage, so the schema already documents `url` (public http(s), length bounds). The description restates 'http/https' and 'public' but adds no syntax or format detail beyond the schema, matching the baseline-3 expectation when the schema does the heavy lifting.

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 up front: 'grade a public page's HTTP security headers.' It then enumerates exactly what is graded (HSTS, CSP, cookie flags, COOP/COEP/CORP, disclosure headers), leaving no ambiguity about scope. An agent can distinguish this from render_page, get_page_meta, or inspect_domain at a glance.

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 bounds usage: 'It grades one response's headers, not the site... and it is not an audit,' and notes private/internal/IP-literal targets are refused. This gives clear when-not conditions, though it never names a specific sibling to prefer for related needs (e.g., get_page_meta for metadata), 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive) the description discloses that signature-database matches are unverified hints, gives a latency range (0.2-1 s), states pricing, rate-limit pooling across three tools, and warns that returned page text and on-chain strings are untrusted data. That is unusually rich behavioral context that 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?

The core purpose and inputs are front-loaded in the first clause, and every sentence carries operational information (mode behavior, latency, price, quota, untrusted-data warning). It is dense and slightly run-on with pricing/quota clauses, but nothing is wasted.

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 sketches the return behavior ('every candidate that decodes cleanly is returned') and adds quota and security caveats. It stops short of describing the actual response shape or how candidates are ordered, which is the one meaningful remaining 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?

Schema description coverage is already 100%, so the baseline is 3. The description adds genuine meaning by explaining what a null/omitted signature triggers (selector lookup with multiple candidate decodings) and by flagging 0x hex format, which is behavior the schema alone does not imply.

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 a specific verb + resource ('decode EVM transaction calldata') with the chainpeek prefix, so an agent immediately knows what it does. It does not, however, differentiate itself from nearby siblings such as decode_tx_logs or get_transaction, so the highest band is not quite reached.

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 clearly explains the two operating modes: supply an optional signature, or omit it and let the selector be looked up with all cleanly-decoding candidates returned. That is real usage context, but it offers no explicit when-to-use / when-not-to-use guidance relative to sibling decoding or lookup tools.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial extra context: the exact slots read, that an upgradeable proxy's implementation can change after the read, that malformed/inconsistent node answers return 5xx uncharged, latency of 1-4s, pricing, and the shared free-tier rate limit. This is far beyond what the annotations provide.

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 core action and inputs before the return field list, then caveats, latency, and pricing. It is a dense single-paragraph block, but nearly every clause carries operational value for a tool with this many return fields; minor density cost only.

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 full burden and does so thoroughly: it enumerates is_contract, is_proxy, kind (with all enum values), implementation and whether it has code, admin, beacon, and raw slots, plus the transient nature of the implementation for upgradeable proxies. Nothing an agent needs to interpret results 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% with an enum on `chain` and a regex pattern on `address`, so the schema already documents both parameters fully. The description restates the same input contract (ethereum|base, 0x+40 hex) without adding new syntax or semantic detail, so the baseline of 3 applies.

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 precise verb+resource: detecting whether a contract is a proxy and which kind, across two named chains. The enumerated `kind` values (eip1967_transparent, eip1822_uups, eip1167_minimal, etc.) make the scope unambiguous and clearly separate it from siblings like scan_contract_source or check_contract_before_interaction.

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 description makes the usage context inferable (you call it to classify a deployed contract), but it never explicitly says when to prefer this over siblings such as scan_contract_address, scan_contract_source, or check_contract_before_interaction. No when-not guidance or alternative routing is offered.

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?

Goes well beyond the annotations: it discloses error semantics (422 not charged, 5xx not charged and why), expected latency, price, a shared free-tier quota, and an explicit untrusted-data warning. Annotations already cover safety (readOnly, idempotent, non-destructive); the description adds the operational and trust posture an agent needs.

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?

Dense but front-loaded: purpose first, then inputs, returns, error behavior, timing, and pricing. Every clause carries information, though the pricing/free-tier detail makes it heavier than a purely discovery-oriented description needs to be.

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 enumerates the return fields (allowance_raw, allowance, decimals, symbol, unlimited) with the 2^255 threshold, and covers error, latency, and cost dimensions needed to call the tool correctly.

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 the four parameters are already documented in the schema, including the chain enum and the 0x+40-hex patterns the description repeats. The description adds no syntax or format meaning beyond the schema, so the baseline of 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 and resource (read an ERC-20 allowance) and scopes it to two named chains. An agent can distinguish this from siblings like get_balance or get_token_info 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?

The description gives clear context for when the tool applies (reading approval state on Ethereum or Base) and adds operational conditions (422 for non-readable ERC-20, 5xx for bad node data). It does not explicitly route the agent away from or toward sibling tools such as check_contract_before_interaction or get_token_info, so a 4 rather than 5.

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 read-only/idempotent safety profile, and the description adds substantial extra context: 1-3 s runtime, USD pricing per section, the 5/day free quota shared across tools, the caveat that it is heuristic not an audit, and a prompt-injection warning about returned text. That is genuinely useful behavioral disclosure beyond 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-loads purpose, then input, then returns, then cost/limits — a sensible ordering. It is dense with many short clauses, but virtually every sentence carries information an agent needs.

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 explains what comes back (DNS records, SPF/DMARC/DKIM/MTA-STS findings with a score out of 8, cert expiry/SANs/key/trust integral). Combined with cost, latency and safety caveats, nothing essential 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 coverage is 100% and the description largely restates schema facts (253-char limit, no scheme/IP, checks defaulting to all three). The only added nuance is that a single section is cheaper, which is minor. 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 (inspect) plus resource (domain's DNS, email auth, TLS cert) and scopes it as a single combined call. It is clearly distinguishable from siblings like ip_lookup, rdap_lookup and verify_email, which each cover only one slice.

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 context on when it applies (one-shot domain inspection), the input constraints, typical latency, cost, and the shared free-tier pool with RDAP/email/IP lookups. It does not explicitly say when to prefer a sibling over this tool, but the surrounding context is clear.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing pricing (USD 0.002), a free tier shared across several lookup tools, latency (0.3-2 s), the 422-not-charged case for private/reserved addresses and non-RDAP TLDs, redaction handling via `redacted` fields, and an untrusted-data warning. This is exactly the behavioral context an agent cannot get from structured fields.

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?

Dense but front-loaded: the purpose and input format come first, then return fields, then error/cost behavior. Nearly every clause carries information, though it is a long single block that could be split for 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 output schema, the description compensates by enumerating the returned fields for domains and for IP/AS queries, plus null/redaction semantics. Combined with cost, latency and error behavior, an agent has everything needed to invoke and interpret the call.

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% and the single `query` parameter is already documented with the same examples in the schema, so the description adds no syntax or format detail beyond it. Baseline 3 applies when the schema carries the parameter burden.

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 (RDAP/whois registration lookup) and enumerates the three accepted query kinds (domain, IPv4/IPv6, AS number). It also spells out what each query type returns, so an agent can distinguish it from sibling lookups without opening the 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?

Usage is implied through the input taxonomy and the 'found:false vs 422' rules, which tell the agent when a result is absent versus invalid. However, it never names alternatives such as ip_lookup or inspect_domain or states when to prefer one over the other, leaving sibling selection 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: nothing is installed, imported or run; sandbox unpacking as text; timing expectations (2-4s registry, 5-15s monorepo, 60s hard limit); timeout results still charged; 503/Retry-After queue sharing; pricing tiers; free-tier pool; version pinning for cache. It even warns that evidence strings are untrusted quoted data and that 'safe-looking' means no rule matched, not harmless.

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 purpose and invocation trigger, and nearly every sentence carries operative information (limits, caveats, pricing, caching). It is a dense single block rather than a structured list, which slightly hurts scannability for such a large volume of detail.

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?

Given no annotations and no output schema, the description compensates fully — it even documents the return shape (verdict, risk_score, one-line summary, file:line findings) and enumerates the finding categories. An agent has everything needed to decide whether to call it and how to interpret 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 description coverage is 100%, so the baseline is 3, but the description adds cost and behavior implications of parameter choices that the schema does not: a whole GitHub repo (no //subdir) or an upload >5 MB costs more, //subdir avoids monorepo timeouts, and uploads are never sent to OSV.dev.

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 ('static security scan of an AI-agent skill (SKILL.md bundle) or MCP server package') and names the exact use moment ('before installing or enabling one'). It is unmistakably distinct from the sibling contract-scanning tools, which operate on a different domain entirely.

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 when: 'Call this before installing or enabling one.' It also supplies when-not/alternative guidance, e.g. scan a //subdir instead of a giant monorepo that would time out, and it defines the boundary of its own coverage (runtime-registered tools, downloaded code, nested archives, obfuscated logic).

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?

With no annotations, the description carries the full burden and does so: it discloses refusal semantics (not_verified, refused inputs never charged), exact pricing tiers and the 15,000 nSLOC ceiling, free-tier quotas, latency bounds (3-30 s typical, 60 s cap), concurrency and queue behavior with 503/Retry-After, and the crucial caveat that findings are heuristic and an empty report is not proof of safety. This is unusually rich disclosure for a mutation-free scan tool.

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?

Dense but front-loaded: the operation, inputs, and the not_verified routing rule come first, followed by price, quota, and timing details. Nearly every clause carries operational weight, though the pricing/latency block could be tightened 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?

No output schema exists, and the description still names the return shape ('JSON report plus a Markdown rendering'). Combined with refusal handling, pricing, quotas, timing, and the audit-vs-heuristic caveat, an agent has everything needed to call this correctly and set expectations for the response.

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 only 40%, and the three undocumented parameters are exactly the opaque ones: include_noisy, include_dependencies, include_informational. The description only refers to them collectively as 'optional include_* flags' without saying what each controls or why an agent would enable it. It does restate address and chain formats, but those are already in the schema, so the coverage gap is not compensated.

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 a specific verb and resource ('static security scan of a deployed contract on Ethereum or Base, by address') and explicitly positions itself relative to siblings: same analysis as scan_contract_source, and check_contract_before_interaction for unverified contracts. An agent can distinguish it from all three siblings 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?

It gives an explicit routing rule for the failure case ('Contracts without verified source are refused (not_verified) ... for those, use check_contract_before_interaction'), and the reference to scan_contract_source implies when this address-based variant is appropriate. It stops short of stating the inverse condition (use scan_contract_source when you already have source), so it is clear context rather than fully enumerated alternatives.

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: pricing tiers and refusal of oversized inputs, no-charge-on-refusal and no-charge-on-503 semantics, free-tier pool, per-scan timeout, queue depth, concurrency limits, Retry-After behavior, expected latency, and the false-positive limitation. This is unusually complete for a tool with zero annotation coverage.

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?

A single dense paragraph, correctly front-loaded with purpose and inputs before cost and SLA details. The operational specifics (price, queue, timeout, refunds) mostly earn their place, though the packing makes it a heavy read and some latency detail 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?

For a 7-parameter, zero-required tool with no output schema, the description supplies everything an agent needs: input shape and limits, parameter defaults, what the report contains (status, findings with severity/confidence/file:line/explanation/recommendation, plus Markdown), and the full cost/latency/error envelope.

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 only 43%, so the description must compensate — and it does for the key parameters: the source vs standard_json trade-off, their size/file limits, filename, and that compiler_version defaults from the pragma. The three include_* flags are mentioned as a group but never individually explained, leaving that gap only partly closed.

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 — 'static security scan of Solidity source code' — and names the exact input forms accepted (single .sol file or solc standard-JSON). This is plainly distinguishable from the sibling tools, which operate on a contract address or an agent package rather than raw source.

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 usage context ('before you deploy, review or depend on a contract') and a strong misuse caveat ('Automated and heuristic, not an audit'). It does not, however, explicitly name when to reach for a sibling tool instead, nor state exclusions beyond the input-size refusals.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: runtime (under 1 s), price (USD 0.001), a shared free-tier quota of 10 calls/IP/day, and an explicit no-logging/no-storage privacy guarantee. That is exactly the extra behavioral context 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?

It is a single dense paragraph that is front-loaded with the purpose and output facets before inputs, pricing, and privacy. Long, but nearly every clause carries information the agent needs given there is no output schema; only the output-facet list could be trimmed slightly.

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 carries the burden of describing returns, and it does so comprehensively (risk, positions, confusables, scripts, normalization status, optional normalized/stripped text). Quota, pricing, and data-handling are also covered, leaving nothing an agent needs to invoke it correctly.

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?

With 80% schema coverage the baseline is 3, but the description names every parameter and adds meaning: the 200,000-character cap, the four normalization forms, and what stripping invisible characters actually removes. The only real gap is that normalize (the one schema param with no description) is listed without explaining the tradeoffs between forms.

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 (inspect) and resource (text for hidden/look-alike Unicode) and enumerates the exact output facets: risk level, invisible characters with positions, bidi/Trojan Source, UTS #39 confusables, combining-mark floods, scripts. This clearly separates it from siblings like text_stats, text_encode, or text_spellcheck.

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 'security-oriented' framing makes the use case evident and the description names concrete attack classes (prompt-injection smuggling, CVE-2021-42574) that motivate calling it. However, it never explicitly states when to prefer this over adjacent siblings or any when-not conditions, so it stops short of a 5.

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?

Far exceeds what annotations provide: it discloses the critical limitation that no SMTP/RCPT probing occurs so mailbox existence is NOT verified, gives expected latency (0.1-1 s), price (USD 0.002), a rate limit (5/IP/day shared pool), and a prompt-injection warning about untrusted page text. These are exactly the traits an agent needs and none are in the structured fields.

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 input, then the checks, then the return shape, then operational constraints. Dense but every sentence carries information; only the long enumeration of checks and returned fields pushes it toward being list-heavy rather than prose.

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 names the return fields (verdict, reasons, normalized, mx_hosts, null_mx, disposable, role_account, free_provider) and the verdict enum values, plus cost, latency and the safety caveat. Nothing needed to call or interpret 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?

Only one parameter and schema description coverage is 100%, so the schema already documents `email` fully; the description's 'Input: `email`' adds nothing beyond the name. Baseline 3 applies when the schema does the heavy lifting.

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?

Specific verb (verify) plus a narrowly scoped resource (an email address) with an explicit boundary: 'syntax + DNS, no SMTP'. The description enumerates exactly what is checked (MX, null MX, A/AAAA fallback, disposable list, role parts), making it clearly distinguishable from siblings like inspect_domain, rdap_lookup, or ip_lookup.

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 situational context: 'before you send to it or accept it at sign-up'. It also hints at the shared free-tier pool with domain inspections, RDAP and IP lookups, but it never names a sibling tool or states when to prefer inspect_domain or rdap_lookup instead, so the routing guidance is implicit rather than explicit.

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