Midkernel Threat Intel

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

Well beyond the annotations, it discloses cost (free, no credits), data exposure (no user data or repositories), response boundedness (complete catalog in one response), semantic caveat (classes can overlap; unknown means no supported assignment, not benign), and detailed rate-limit behavior including 429 meaning, Retry-After, and backoff with jitter.

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 cost, then semantics, then operational caveats. The final two sentences on rate limiting are longer than necessary for a catalog read but still convey actionable retry instructions, so only a small deduction.

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 and no annotations for return shape, yet the description says the complete bounded catalog comes back in one response, so the agent knows what to expect. It never describes the returned fields (ID plus taxonomy version), which is the main 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?

Zero parameters means the baseline is 4, and the description confirms 'No arguments.' It adds marginal value by explaining how IDs produced here are consumed by ti_latest.class, though there are no arguments of its own to explain.

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 ('List every supported Threat Intel class ID and the taxonomy version') and immediately scopes it as taxonomy discovery rather than observed counts, which separates it from ti_latest, ti_trends, and ti_daily_report. An agent can pick this tool 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 routes the agent downstream: 'Use the exact ID in ti_latest.class' and clarifies unknown IDs are rejected, plus contrasts discovery vs. observed counts. It stops short of a full when-not-to-use statement for the other siblings (ti_sources, ti_get), so not 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?

Goes well past the annotations (readOnly/idempotent/closed-world) to disclose that late arrivals and source revisions mutate the report, that ordering is attention-based rather than risk-probability, that counts are collected evidence and absence is not proof of safety, and that source text is untrusted data. It also specifies operational behavior: sequential calls on the public endpoint and that HTTP 429 with Retry-After means admission denial, not an empty 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?

The window definition and mutability caveat are front-loaded, which is good, but the description runs to roughly ten sentences for a zero-required-parameter read tool. Several ideas repeat (counts vs. attacks, absence not proof, caveats/citations), so it is dense rather than lean.

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 signals what comes back (findings, caveats, citations, counts) and covers the clock window, mutability, trust handling, and rate-limit recovery. It stops short of describing the actual response fields or pagination, which is the remaining gap for a tool with no output schema.

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 optional parameter (limit) exists and the schema documents it fully at 100% coverage, so the baseline is 3. The description adds nothing about limit — neither its default/ceiling nor how it interacts with the bounded report — so it does not exceed 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?

States a specific verb and resource ('Read a bounded daily report of public-source Threat Intel') with an explicit scope: the previous complete UTC day, selected by source-effective publishedAt. It never names a sibling (ti_latest, ti_get, ti_trends) to draw the boundary, so differentiation is inferable but not explicit.

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

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

Usage context is clear — a fixed, non-overridable previous-day window and a note that this is a current view rather than a snapshot. However, there is no explicit 'use this instead of ti_latest when…' routing, so an agent must infer the choice between this and its five 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 read-only/idempotent semantics, and the description adds substantial context beyond them: cost ('Free; no user data or credits'), the KEV-absence caveat, the rule that retained withdrawn/excluded evidence is provenance and not active analytics, a prompt-injection warning about untrusted source text, and sequential-call plus HTTP 429/Retry-After handling on the public endpoint.

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 and input sourcing are front-loaded, and most sentences carry distinct operational value (cost, provenance, pagination, rate limits). It is longer than average and the safety/rate-limit guidance could be tightened, but no sentence is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description still tells the agent what comes back (record, retained evidence, revisions, KEV join) and warns about interpretation pitfalls in the returned evidence. Combined with the rate-limit and untrusted-content guidance, nothing an agent needs to call and interpret this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including the id forms and the meaning of revisionPage and observationPage. The description adds only a light nudge ('Follow evidence pagination when needed') that maps loosely to observationPage but says nothing extra about the two page parameters or their limits, 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 specific verb and resource: 'Read one Midkernel Threat Intel record, retained evidence and revisions, plus KEV evidence joined via CVE.' It also names the accepted identifier forms, which lets an agent separate this fetch-by-id tool from sibling listing tools like ti_latest 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?

'Use a record id from ti_latest, a CVE, or a GHSA id' gives an explicit source for the input and implicitly routes discovery to ti_latest. It does not explicitly exclude any sibling (e.g., ti_daily_report or ti_trends) or state when this tool should not be used, so it stops short of full when/when-not guidance.

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, but the description adds what they cannot: free/no-auth/no-credit model, page-size asymmetry (200 full vs 500 summary), checkpoint overlap requiring (id, matchedAt) dedup, 429 meaning admission denial rather than empty result, and Retry-After/backoff-jitter retry policy. It also flags source text as untrusted data rather than instructions, a genuine safety behavior.

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 packs distinct operational facts with no filler sentences; nearly every clause conveys non-obvious behavior. It is dense and slightly run-on in places (the timeField paragraph and the rate-limit tail), costing a perfect score, but nothing meaningful reads as 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?

For an 8-parameter, no-output-schema tool it covers the hard parts: time-window bounds, clock choice, pagination/checkpoint continuity, dedup, and rate-limit recovery. The remaining gap is return shape — nextCursor and checkpoint.since are referenced as if known, and with no output schema the description never states what a record or the checkpoint object actually contains.

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 earns above that by adding constraints the schema omits, notably that until must be at most 60 days later and that firstSeenAt reflects the source-release clock which can predate archive-replay arrival. It also ties format to record caps and warns that filters must stay identical across cursor pages. The limit and cursor parameters are handled only briefly in comparison.

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 ("Read new or changed threats from Midkernel's public-source Threat Intel") and scopes it as a delta feed rather than a lookup. It differentiates itself from ti_trends explicitly and routes discovery to ti_classes/ti_sources, though it never contrasts with ti_get or ti_daily_report, leaving that inference to the agent.

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 guidance: "Use changedAt for alerts," changedAt vs firstSeenAt semantics including the archive-replay caveat, and "discover exact IDs with ti_classes and ti_sources." It also states the follow-up procedure (paginate with nextCursor under identical filters, then checkpoint.since for the next poll) and the sequential-call requirement on the shared public endpoint.

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 closed-world, and the description adds substantially more: no credits or user data consumed, the entire bounded catalog returns in one response, registration does not guarantee live collection, and calls must be sequential on the public endpoint. It further explains that HTTP 429 signals admission denial rather than an empty result and prescribes honoring Retry-After with jittered backoff — exactly the operational context 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 the resource and returned fields, then follows with the ID-reuse rule and the rate-limit protocol. Every sentence carries operational information, but the rate-limiting tail is dense enough that it slightly dilutes the core catalog purpose.

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 and states that the catalog is complete and bounded in a single response, so the agent knows the shape and extent of the result. Combined with the rate-limit and ID-reuse guidance, nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing to disambiguate and the description correctly states 'No arguments.' Baseline for a parameterless tool applies; the extra note about using the returned ID elsewhere is useful but belongs to usage rather than parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) plus the exact resource and returned fields: configured public Threat Intel source ID, name, format, surface and source URL from the pinned collector registry. It also implicitly distinguishes itself from siblings by naming ti_latest.source as the consumer of these IDs.

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 says to use the exact returned ID in ti_latest.source and that guessed aliases are rejected, which routes the agent correctly. It also states 'No arguments' so the agent knows no query shaping is possible, though it does not explicitly say when to prefer ti_get or ti_classes over this catalog.

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?

The description adds substantial behavioral context beyond the read-only, idempotent, non-destructive annotations: the 60-day window cap, comparison against a preceding equal-length window, evidence-not-attacks caveat, overlapping classes/sources, withheld nulls, zero-baseline percentage behavior, untrusted source text, sequential calls on the public endpoint, and 429/Retry-After handling. These are meaningful operational and interpretive constraints that the annotations do not cover.

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 and most sentences earn their place by conveying constraints, caveats, or retry behavior. The description is dense and could be structured more clearly, but the length is largely justified by the operational details it must convey.

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 read-only analytics tool with a nested window parameter and no output schema, the description covers window semantics, comparison behavior, grouping, null/percentage handling, and rate-limit behavior well. It stops short of fully describing the output shape, but the remaining gap is relatively minor given the rich behavioral coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents window.from, window.to, date patterns, inclusivity, and groupBy enum values, giving 50% coverage overall. The description mainly adds the 60-day cap and reiterates grouping by class, source, or day; it does not add much more parameter-level semantics 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?

The description states a specific verb and resource: it compares canonical threat counts over a window against the immediately preceding equal-length window, grouped by class, source, or day. This is clear enough to distinguish trend-analytics behavior from simpler sibling tools, although it does not explicitly name those siblings as alternatives.

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 by the comparison-over-window framing and the 60-day window limit, but the description does not explicitly say when to use ti_trends versus ti_latest, ti_daily_report, ti_classes, or ti_sources. It gives operational guidance for the public endpoint and 429 responses, but not clear selection guidance among sibling tools.

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