Jeevesus — DugganUSA threat-intel MCP

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

Consistent with readOnlyHint=true and openWorldHint=false, and adds real behavioral context the annotations cannot: prices are dated snapshots from provider pages, public read with no auth, and unknown models return UNPRICED rather than $0 — a critical anti-hallucination detail.

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 what the tool does, then behavior, then mode examples — easy to scan. Slight redundancy between the rate enumeration in paragraph one and the example in paragraph two, but every sentence carries 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?

No output schema exists, and the description compensates by describing the returned rates, the checked date, the source page, and the cost breakdown. Combined with the UNPRICED sentinel and no-auth note, an agent has everything needed to call and interpret results.

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 only 29% schema coverage across 7 params, the description carries the burden well: it explains that model IDs are provider-specific strings, that token counts produce a cost breakdown, and enumerates the cache-write/read and fast-mode rates. It does not separately define cache_write_5m vs cache_write_1h or the `fast` flag, leaving small gaps.

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 ('looks up') and resource ('what an AI model or an agent session costs at list price'), plus clarifies the pricing basis (dated, copied from provider pages). No sibling tool covers pricing, so there is no ambiguity to resolve.

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 describes two modes: no args lists all priced models and checked dates, and supplying token counts yields an exact call/session cost. It gives a concrete invocation example, though it never states when *not* to use it or a boundary (e.g. non-list/negotiated pricing).

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 only declare readOnly and openWorld; the description goes far beyond by disclosing 'one tool call, no auth', the size and curation of the deny-list (230k+ entries), thin RubyGems coverage, zero Packagist deny-list entries, version-aware matching semantics, and the rule that CVEs yield verdict:'review' rather than block. It also documents the exact 'malicious:true' versus 'malicious:false' meaning, which is the key behavioral distinction 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?

Front-loaded with purpose, then return shape, then semantics, then examples — a sensible order with almost no filler. It is somewhat long and the examples restate the verdict logic already given in prose, but each sentence carries substantive information rather than 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 still enumerates the returned fields ({ecosystem, package, version, malicious, verdict, reason, advice, source}) and explains the verdict values, so an agent knows exactly what it will receive. Combined with the coverage caveats and auth disclosure, 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?

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds real meaning beyond the schema: the github-actions name format (owner/repo@v45.0.7 or name + version) and the advice to pin a full commit SHA for the strongest check, plus the note that version-scoped entries make the check version-aware while all-versions-malicious packages block on any version.

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: checks whether a dependency in named ecosystems is on a malicious-package deny-list or has advisories. Scope (four ecosystems plus GitHub Actions) is stated up front, so an agent can tell instantly this is a supply-chain lookup, not a generic search or enrichment call like its siblings.

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 situates the tool as a pre-install step in an agent or CI pipeline and names the threat model (slopsquatting, hijacked packages). It also gives decision guidance on interpreting outcomes — 'absence is NOT proof of safety, so still pin and review new deps' — and notes the coverage caveats for RubyGems and Packagist that determine when the tool is less authoritative.

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 and openWorldHint=false, but the description adds important behavioral context: it is static and local, nothing is fetched, run, or stored, no auth is needed, and results are limited to the files supplied. It further clarifies what 'no-findings' and 'unknown' mean, which prevents overtrusting the verdict.

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 front-loaded with when to use it and what it checks, then moves to input constraints and return semantics. It is long, and the Binance theft anecdote plus the long pattern list are more verbose than strictly necessary, but most sentences carry operational or safety-relevant 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?

There is no output schema, but the description fully explains the return contract: verdict values, findings shape, coverage, and note. It also covers input limits, relevant files to send, the whole-directory alternative, and the key limitation that 'no-findings' does not mean safe.

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 defines the single files map. The description still adds useful semantic detail by explaining the expected shape, giving representative paths, and stating the 40-file / 28,000-character limit. The only minor ambiguity is that the schema’s maxLength is per file value while the prose says '28000 characters in total.'

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 (check a repository) and enumerates exactly what it inspects: install hooks, VS Code tasks, agent hooks, MCP servers, devcontainer commands, npm registry settings, URL/git dependencies, and setup.py execution. It also distinguishes the tool from a dependency check by saying it looks where 'a dependency check never reads.'

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 usage conditions: before opening or running a repository someone else sent you, including recruiter coding tests, downloaded zips, and proofs of concept. It also names the alternative for a whole directory: use the command line scanner or the DugganUSA Checks GitHub Action.

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 say read-only and closed-world; the description goes further by stating nothing is fetched, run or stored, that no auth is needed, and that it is one call. It also pre-empts the two most dangerous misreadings of the result: 'no-findings' does not mean safe, and '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-loads the purpose and the detection categories, then moves to operational facts (static/local, size limit, return shape). The detection enumeration is dense but each item earns its place by telling the agent what will be flagged; the sourcing sentence is the only piece that 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 contract itself, giving verdict values, the findings array shape with per-finding fields, and coverage/note fields. Combined with the analysis scope and limits, an agent has everything needed to call it and 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 coverage is 100% and the single parameter's description already defines the workflow text, so the description cannot add much. It restates the max-length constraint and the 'pass as text' framing, which is consistent with the schema but not additive. 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?

Names a specific verb (checks), a specific resource (the text of one GitHub Actions workflow file), and the exact class of defect (script injection) with an enumerated list of patterns. Explicitly scoped to a single workflow's YAML text, which distinguishes it from the repository-level siblings like check-repo.

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?

States the input mode ('Pass the workflow's YAML as text'), the size ceiling (28000 characters), and an alternative for whole repositories (DugganUSA Checks GitHub Action). It does not, however, clarify the relationship to the sibling check-repo tool, so an agent must infer which to use when it has a repo rather than a file.

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 only cover readOnly/openWorld; the description adds genuine behavioral depth beyond them: attribution precedence (first-party → curated → third-party, "not necessarily the highest confidence"), the `sources` list cap of 10, and the first_seen vs ingested_at distinction. It also flags real edge cases — `found: false` does not mean safe, and country is often absent.

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 return-value block earns its space since there is no output schema. However, the first two sentences redundantly restate the same indicator-type list, and the long parenthetical about first_seen/ingested_at is dense to parse in one pass.

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-shape burden and does so thoroughly: attribution class, actor, per-source confidence, timestamps, and truncation limits. Missing-data and not-found behavior are both covered, leaving nothing an agent needs to call 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?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by showing concrete indicator formats via three worked examples. It does repeat the schema's alias note ("Pass the IOC as either `indicator` or `value`") and its type list omits the `email` value present in the schema enum, a minor 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 ("Look up a single indicator of compromise (IP, domain, URL, or hash) in the DugganUSA corpus") and explicitly locates itself relative to the `search` sibling. An agent can distinguish it from `search` and the check-* tools 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?

Gives clear usage context: "Useful after `search` finds something, for the full attribution and cross-feed correlation, or directly when triaging a single indicator." That names the alternative and the condition selecting it, but offers no when-not-to-use or boundary against the other siblings (check-package, check-repo, kev-*).

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 readOnlyHint/openWorldHint annotations, it discloses that results are computed live, enumerates what is returned (rho, repeat-offender vs first-time split, concentration share, an `interpretation` sentence), states it is a public no-auth read, and adds an honest caveat that this is a proxy for exploitation dynamics rather than proof of exploit timing.

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 purpose and use case, and the rhetorical 'STICK vs SPREAD' framing efficiently conveys the analysis. There is mild redundancy between the opening 'for patch prioritization' and the later 'how should I prioritize patching' question, plus a duplicated mention of the 30-720 window.

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 returned metrics and interpretation field, states the auth model, the default window, and the interpretive limits of the result. An agent has everything needed to decide to call it and to read its answer.

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 `days` parameter already documents range and default, so the description adds no meaning beyond it — it simply restates '30-720, default 180'. Baseline 3 applies when the schema does the work.

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 verb and resource: it measures whether product-level exploitation risk is chronic or one-off by correlating CISA KEV historical counts against recent additions via Spearman rho. The explicit 'product-level' framing also separates it from the sibling kev-vendor-risk, which operates at vendor level.

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 frames the decision context clearly ('how should I prioritize patching — chase the chronic offenders, or watch for newcomers?') and names the intended use for patch prioritization. It stops short of explicitly saying when NOT to use it or naming kev-vendor-risk as the alternative for vendor-level questions.

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 annotations already covering read-only and closed-world, the description adds substantial context: public read with no auth, CISA source synced daily, results ordered most-recent-first, capped at 50, and return fields kev_count/truncated/ransomware flag despite no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but examples are repeated (Adobe, Citrix and the empty-args example each appear twice across the body and closing line), and the KEV definition is restated, adding redundancy rather than 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 single optional-parameter lookup with no output schema, the description covers what is returned, ordering, truncation, the ransomware flag, auth expectations, and data freshness — everything needed to call and interpret 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?

Schema coverage is 100% so the parameter is already documented, but the description adds behavioral meaning beyond the schema: omitting vendor yields a top-vendor ranking, while supplying one returns that vendor's CVEs newest-first with the ransomware flag.

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 concrete verb+resource: it returns a vendor/product risk ranking and per-vendor known-exploited CVEs from the CISA KEV catalog. The exploitation-concentration framing distinguishes it conceptually from kev-exploitation-stickiness, but that sibling is never named so differentiation is left implicit.

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 scenarios: 'what should I patch first', third-party/supply-chain assessment, and checking whether a fresh PoC sits on a chronically-exploited product. Both call modes (empty args vs vendor arg) are described, but no alternative tool is named for overlapping queries.

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 readOnlyHint annotation it discloses hybrid keyword+semantic retrieval, prompt-injection sanitization, the 25-hit cap, the exact per-hit return fields, `returned` and `indexes_unanswered` in the payload, and the notable absence of a total match count. That is substantive behavior an agent cannot infer 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?

Front-loaded with the one-sentence purpose before the operational detail, and the bulleted index lists are high-value rather than filler. Slight redundancy in restating read-only/sanitization and the trailing examples, but nothing is wasted enough to hurt.

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, yet the description specifies the return envelope and per-hit fields, the result cap, and the timeout signaling. Combined with annotations and a fully described schema, an agent has everything needed to call it and interpret 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 coverage is 100%, so the schema already documents all three parameters; the description goes further by explaining what each index actually contains (iocs, adversaries, cisa_kev, pulses, blog vs. the four archives) and how naming indexes changes scope. The semantics of `limit` beyond the schema max are not expanded, keeping it just short of 5.

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 (searches) and resource (threat-intelligence records), enumerates the record types covered, and explicitly excludes general programming/web content. An agent can distinguish it from siblings like enrich-ioc or the kev-* tools from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use: default index set is named, archive indexes are 'searched only when named', and the 'holds no general programming or web content' line rules out misuse. Three worked examples show query and indexes combinations that select the right behavior.

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 readOnlyHint/openWorldHint annotations, the description discloses the hard cap of 5,000 indicators, the 1–7 day bounding window, a 10-minute cache, and that the call is public/no-auth while the underlying bundle requires a free API key. It also points to bundle_url for the data this tool deliberately omits.

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 opening sentence is well front-loaded, but the usefulness rationale is stated twice — 'feed freshness' in the first paragraph and 'gauge feed depth and freshness' in the third, plus a nearly identical closing example sentence. Roughly one paragraph of the five is redundant.

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 return-value burden and does so thoroughly: window counts, top families vs. list labels, source feeds, indicator-type breakdown, countries, and bundle_url. An agent knows exactly what it will get back and what it will not.

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 one parameter at 100% schema description coverage, the schema already carries the bounds and default, so the baseline applies. The description reinforces the 1–7 day window semantics and provides an example call (`{"days": 7}`), but adds no syntax or interpretation beyond that.

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 shape report over the most recent 5,000 indicators in the DugganUSA STIX 2.1 feed — and enumerates the outputs (counts, top families/labels, source feeds, type breakdown, countries). It clearly distinguishes itself from a full bundle download, though it never names or contrasts with the sibling tools (search, enrich-ioc, check-package).

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 use cases: gauging feed depth/freshness, planning SIEM or blocklist ingestion budgets, spot-checking that a campaign is in the corpus, and using it *before* pulling the full bundle. It also sets a boundary (does not return the bundle), but stops short of saying when another tool would be the better choice.

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