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.