Jeevesus — DugganUSA threat-intel MCP

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond that: prices are dated and sourced from provider pages, the returned fields include the checked date and source page, Anthropic-specific cache and fast-mode rates are enumerated, and unknown models return the sentinel UNPRICED rather than $0. The "public read (no auth)" note is exactly the kind of context 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?

Front-loaded with the purpose, then return contents, then two concrete invocation examples including a literal argument object, then the auth note. Every sentence carries information, but the parenthetical enumerating cache rate types is dense and slightly harder to scan than the rest.

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 the return shape, and it does: per-1M-token USD rates, checked date, source page, and a cost breakdown. Auth, currency, rate units, and the UNPRICED edge case are all covered. Minor gaps remain around cost-breakdown structure (whether a total is included) and rounding precision.

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 29%, so the description must compensate, and it largely does: it explains that token counts turn the lookup into a cost computation, that omitting model lists everything, that cache write rates split into 5-minute and 1-hour, and that fast mode is a premium Anthropic rate. It does not spell out per-parameter behavior for each of the four token fields (e.g. how cache_write_1h_tokens interacts with cache_read_tokens), leaving some mapping to inference.

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: "Looks up what an AI model or an agent session costs at list price." It also scopes the data source ("copied from each provider's own pricing page") and names the two modes (list all models vs. compute cost). None of the sibling tools (check-package, search, enrich-ioc, etc.) overlap, so no differentiation is needed.

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 invocation contexts: no args lists every priced model with checked dates; passing token counts yields an exact cost for a call or session. It also states the edge-case behavior (UNPRICED, never $0) and that no auth is required. It stops short of stating when an agent should prefer this over estimating from memory, but with unrelated siblings no alternative routing is required.

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/openWorld, and the description still adds substantial behavioral context: no auth, one call, the exact verdict vocabulary, the meaning of malicious true vs false, and the important caveat that absence from the deny-list is not proof of safety. It also discloses coverage asymmetries (thin RubyGems, zero Packagist entries) that materially change how the result should be interpreted.

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 verdict shape and caveats before the examples, and every paragraph carries information. The examples block is somewhat repetitive of the prose and the parenthetical ecosystem alias detail overlaps the schema, so it is slightly longer than strictly needed.

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 fully compensates by spelling out the returned object fields, verdict semantics, and version-aware behavior, plus auth-free operation and coverage limits. An agent can call this and interpret the result correctly without further information.

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; the description goes beyond it by explaining that supplying a version makes the check version-scoped, that all-versions-malicious packages block on any version, and that known CVEs downgrade a reputed package to 'review' rather than 'block'. The github-actions owner/repo@ref convention is covered largely by the schema wording, so the gain is real but partial.

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 whether a dependency ... is on the DugganUSA malicious-package deny-list') and enumerates the covered ecosystems, so the agent knows exactly what class of question this answers. It does not explicitly distinguish itself from the sibling tools check-repo and check-workflow, which is the one thing keeping it from a 5.

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 clear usage frame ('suited to a pre-install step in an agent or a CI pipeline, against slopsquatting and hijacked-package attacks') and practical guidance to pin full commit SHAs and review new deps. It lacks an explicit exclusion rule pointing at siblings for repo- or workflow-level checks.

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 read-only, local, idempotent, non-destructive, but the description adds the crucial operational facts: static and local, nothing fetched, run, or stored, one call, no auth. It also pre-empts the most dangerous misreading by defining that 'no-findings' means only that the listed patterns were absent from the submitted files, not that the repo is safe, and that 'unknown' means nothing was analyzed.

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 action and the verdict framing, then detection scope, then input limits, then return shape and the caveats — a sensible order. It is dense but long, and the Binance theft/recruitment-test backstory plus the near-duplicate restatement of the 40-file/28000-character caps already in the schema are the sentences that earn their place least.

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 single-parameter tool with no output schema, the description supplies everything an agent needs: input shape and limits, which files to send, the four possible verdict values with their meanings, the findings record fields, the presence of coverage and note, and the explicit non-guarantee of 'no-findings'. The limitations are stated rather than hidden.

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 schema documents the path-to-text map, so the baseline is met. The description goes beyond it by explaining the caps in prose (at most 40 files, 28000 characters total) and, more usefully, by naming the high-value paths to include — package.json, .vscode/tasks.json, .claude/settings.json, .mcp.json, .devcontainer/devcontainer.json, .yarnrc.yml, .npmrc, setup.py, plus any suspicious script — which is selection guidance the schema cannot express.

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: pass a stranger's repository files in and get a verdict on run-on-open and install-time lures. It enumerates the exact pattern classes it detects (npm install hooks, VS Code run-on-open tasks, .claude/.cursor/.mcp.json agent hooks, devcontainer initializeCommand, yarnPath, git/URL deps, decode-and-eval payloads, setup.py fetches), which clearly separates it from siblings like check-package and check-workflow.

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 frames the when: before opening or running a repo someone else sent you, with concrete triggers (recruiter coding test, downloaded zip, PoC). It also names the alternative paths for a different scope — the command line scanner or the DugganUSA Checks GitHub Action for a whole directory — and states the safety prerequisite of reading code on a credential-free machine.

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, non-destructive and closed-world, and the description adds genuinely new behavior: nothing is fetched, run or stored; the 28000-character input cap; and, most importantly, the interpretation of the verdict values, including that 'no-findings' does not mean the workflow is safe and that 'unknown' means nothing was analyzed. That caveat is exactly the kind of context an agent needs to avoid over-reporting a clean result.

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 the detection classes, then limits, then return semantics — a sensible order with no filler sentences. The provenance sentence about the Radware report and the named third-party Action are slightly promotional and only marginally aid invocation, keeping it out of the top score.

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 specifies the return shape: verdict enum with five values, the fields of each finding, plus coverage and note. Combined with the input cap and the stated analysis scope, an agent has everything needed to call this once and interpret the result 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 coverage is 100% for the single parameter and the maxLength of 28000 is already declared in the schema, so the description's restatement adds no new constraint. It does clarify that the value is the file's YAML text for a file under .github/workflows, but that is close to what the schema property description already says — baseline 3.

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 one GitHub Actions workflow file) and then enumerates the exact classes of defect it detects — user-controlled text pasted into shell/github-script, privileged PR-checkout triggers, eval re-evaluation, open token permissions on externally triggerable workflows, and AI agent actions. An agent can distinguish this from check-repo or check-package purely from the description.

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: pass a single workflow's YAML as text, and use a different mechanism (the DugganUSA Checks GitHub Action) when the target is a whole repository. That is an explicit scope boundary, though it does not name any of the sibling MCP tools as an alternative, so an agent must infer the contrast with check-repo.

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 annotations it discloses a great deal: `held` vs `held_in` lane attribution, co-tenant false-positive risk from shared hosting/cloud ranges surfaced via `caveats`, truncation signaling with `truncated:true` at the scan bound, `block_coverage` being reported separately from a detection, and tier-based response differences for Pro/Enterprise versus free/anonymous callers. It also states what is explicitly not consulted (edge observations, honeypot hits).

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 front-loaded with the two-question framing and organized into tight paragraphs covering returns, strength, usage, and exclusions. The field-name-heavy prose is dense but every paragraph carries information an agent needs; there is little filler, though the length is at the upper end for a two-parameter 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so field by field (held, held_in, neighbors, neighbor_summary, block_coverage, strength, caveats, neighbors.sample). Combined with the usage and exclusion guidance, an agent can call this correctly and interpret the result without further context.

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 both parameters are already documented, including the `limit` note that counts and summary do not depend on it. The description reinforces the accepted indicator types (IPv4 or domain) and explains why `limit` only affects Pro/Enterprise sample rows, adding modest but real meaning on top of the schema.

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 precise framing of the two questions it answers ('do we HOLD it, and what sits NEXT to it') and names the concrete resources involved: IPv4 addresses and domains. It clearly separates itself from `enrich-ioc` by defining correlation as graph/lane membership rather than enrichment.

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 explicit when-to-use conditions ('after `enrich-ioc`, or first, when the question is "is this part of something"') with concrete motivating examples (scanner next to known C2, lookalike domain, clean address in dirty /24). It also states the exclusions outright: hashes and URLs are not graph nodes, use `enrich-ioc` for those.

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 annotations, the description discloses the attribution selection logic (first-party, then curated, then third-party, not necessarily highest confidence), the fields returned for the strongest record and sources, the difference between `first_seen` and `ingested_at`, and the important caveat that `found: false` does not mean the indicator is 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?

The description is well structured with front-loaded purpose, usage guidance, return semantics, and examples. It is somewhat verbose for a single-indicator lookup, and the first two sentences redundantly restate the same lookup action.

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, but the description thoroughly explains what is returned, including attribution, actor, source list fields, source count limits, and the not-found behavior. It also notes that country is only populated when the source provides it, which is the kind of operational caveat an agent needs.

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 schema already documents the parameters and aliases. The description reinforces that `indicator` and `value` both work and gives example values, but its type hint list omits `email`, which the schema enum includes, so it adds only marginal parameter meaning and introduces a small omission.

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 and resource: look up a single indicator of compromise in the DugganUSA corpus. It explicitly scopes the tool to one IP, domain, URL, or hash and distinguishes its role from `search` by describing enrichment after search or direct single-indicator triage.

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 clear usage context: useful after `search` finds something, for attribution and cross-feed correlation, or directly during triage of a single indicator. It names the relevant sibling and implies single-indicator scope, but does not explicitly state when not to use this tool versus other 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 cover the safety profile (read-only, idempotent, non-destructive, closed-world), and the description adds genuinely useful context beyond them: results are computed live, the exact output components are enumerated (rho, repeat/first-time split, top-20 concentration share, interpretation sentence), and it flags that the metric is a proxy rather than exploit-timing proof. Authentication state ('public read, no auth') is also stated, which annotations do not 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?

Purpose is front-loaded in the first sentence, then mechanics, then the decision framing. Slightly redundant: the 'chase the chronic offenders, or watch for newcomers' question partly repeats the opening stickiness question, and the ALL-CAPS emphasis adds length without 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?

For a one-optional-parameter tool with no output schema, the description carries the right load by enumerating return components and disclaiming interpretation. The only gap is that it never indicates how to read rho direction or magnitude, relying entirely on the returned `interpretation` sentence.

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 single `days` parameter, its 30-720 bounds and its default are already documented in the schema. The description restates the range and default and clarifies that the window defines which additions count as 'recent', but adds no guidance on how window length shifts the rho result. 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 analytical operation: it correlates each product's historical KEV count against recent KEV additions via Spearman rho and splits repeat-offenders from first-time products. The verb+resource is concrete and product-level scope is explicit. It loses a point for never naming the closest sibling, kev-vendor-risk, so the agent must infer the vendor-vs-product distinction itself.

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?

Frames the decision it informs ('chase the chronic offenders, or watch for newcomers') and discloses the caveat that this is a proxy for exploitation dynamics, not proof of exploit timing. However, it gives no explicit when-to-use-this-instead-of guidance relative to kev-vendor-risk, and no exclusion conditions, leaving the sibling choice 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower — yet the description still adds real value: no auth required, source is CISA KEV synced daily, results are most-recent-first capped at 50, and each record carries a ransomware-use flag plus kev_count/truncated metadata. That is return-shape and operational 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?

Content is front-loaded — the one-line hook, then the data source, then per-mode behavior, then use cases, then auth/sync note. It is somewhat longer than needed: the "what should I patch first" framing appears twice and the KEV-means-confirmed-exploitation point is restated in the second and sixth blocks. Trimming that repetition would tighten it 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 one optional parameter and no output schema, the description carries the burden of describing returns — and it does, covering ranking output, per-vendor CVE lists, ordering, the 50-item cap, the ransomware flag, kev_count, and truncated. Auth requirements and source freshness are also stated, so nothing an agent needs to call this 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%, so the baseline is 3; the description exceeds it by explaining that omitting the parameter yields the ranked vendor matrix and that the parameter accepts product names as well as vendors ("an appliance, an ERP," ColdFusion, SharePoint, NetScaler). It clarifies the semantic breadth of a single string field rather than just restating it.

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 and resource: it shows where confirmed exploitation concentrates per vendor/product, built from CISA's KEV catalog, and it explicitly explains the two modes (no args = top-vendor ranking, vendor arg = that vendor's CVEs). An agent immediately understands the resource and scope. It stops short of a 5 because it never differentiates itself from the close sibling kev-exploitation-stickiness, leaving the agent to guess which KEV view to pick.

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 context is unusually concrete: "what should I patch first," third-party/supply-chain exposure assessment, and checking whether a fresh PoC lands on a chronically-exploited product. That covers multiple when-to-use scenarios. There are no explicit when-not conditions or named alternatives (e.g. kev-exploitation-stickiness, check-package), which keeps it below 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?

Annotations already declare read-only, idempotent and non-open-world, yet the description still adds real behavior: hybrid keyword+semantic matching, prompt-injection sanitization, a hard 25-hit ceiling, per-hit field contents with nullable url, and the caveats that no total match count is returned and that `indexes_unanswered` flags timed-out indexes. This is the kind of partial-failure and result-shape information 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-loaded with purpose then result contract, then the index taxonomy, then examples—a sensible ordering. The bulleted index lists are dense but earn their space; only the 'live counts: /api/v1/search/stats' endpoint mention and the fairly long enumeration of per-hit fields feel like marginal padding.

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 contract itself and does so thoroughly: hit fields, `returned`, `indexes_unanswered`, and the explicit absence of a total count. Combined with index scoping and example queries, an agent has enough to call this correctly and interpret the response, with only query-syntax detail 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%, so a 3 is the floor, but the description goes beyond it by explaining what each index actually contains (iocs with actor attribution, 366 adversary profiles, daily-synced CISA KEV, OTX pulses, 1,800+ blog posts) and why the archives are opt-in. It adds no guidance on `query` syntax—no mention of phrase, boolean, or field-prefix support—and `limit` is left entirely to the schema.

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?

Opens with a specific verb and resource ('Searches threat-intelligence records about threat actors, malware, campaigns, CVEs, breaches, vendors and indicators') and immediately bounds the scope ('no general programming or web content'). An agent can distinguish this from enrich-ioc, correlate, or check-package without opening any 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?

Explicitly states the default index set, that archive indexes are 'searched only when named', and that non-security content is out of scope, plus three worked examples showing index selection. It does not route the agent to sibling tools (e.g., when to prefer enrich-ioc or correlate over a broad search), which keeps it from 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?

Adds substantial behavior beyond the annotations: the 5,000-indicator cap, the 1–7 day bound, a 10-minute cache, no-auth public read, and the fact that the full bundle lives at bundle_url and requires an API key. It also discloses edge behavior (feeds like Spamhaus DROP label by list rather than family; countries only present when records carry one), which the readOnly/idempotent 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-loaded with purpose and return shape before caveats, and every paragraph is structurally distinct. There is some redundancy — SIEM ingestion planning is mentioned twice and the example sentence repeats capacity-planning framing already stated above.

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 carries the burden of explaining return contents, and it does so exhaustively (counts, top families/labels, top feeds, type breakdown, countries, bundle_url). Auth, caching, and cap constraints are all covered for a single-parameter read 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% (min 1, max 7, default 1), so the baseline is 3, but the description adds meaning the schema does not: how the window interacts with the 5,000 cap, and a worked example `{"days": 7}`. Marginal but genuine added value over the schema.

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?

Opens with a specific verb and resource ("summarizes what is in the feed right now") and then enumerates exactly what the report contains: counts in window, top malware families or list labels, top source feeds, indicator-type breakdown, and top countries. It also explicitly distinguishes itself from the full STIX bundle, so an agent knows this is an aggregate view, not the data pull.

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 concrete when-to-use conditions ("what's active this week", feed freshness, planning SIEM/blocklist ingestion, checking a campaign is in the corpus) and names the alternative it precedes ("use before pulling the full STIX bundle"). It does not differentiate against the listed sibling tools such as enrich-ioc, correlate, or search, so routing between those 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.