Nullcone Threat Intelligence

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

With no annotations, the description fully discloses behavior: the check is <1ms with no network I/O, the effect of block_on_stale (hard block vs warn), and the exact return fields. This is complete behavioral transparency beyond what any annotation could 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?

The description is well-structured with sections for usage, mapping, args, and returns. Every sentence adds necessary value, and the length is justified by the absence of an output schema and annotations. 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?

Given no annotations and no output schema, the description provides everything needed: the staleness tier mapping, parameter semantics, and a full return field list. It is entirely self-contained and complete for the tool's complexity.

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 0%, but the description thoroughly explains both parameters: action (with a default tier for unknown actions) and block_on_stale (with default behavior and outcome). This compensates entirely for the sparse 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?

Description clearly states 'Validate that IOC threat intelligence is fresh enough for the named action' – a specific verb and resource. It distinguishes from siblings by focusing on TI freshness, not prompt checking or other threat operations.

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?

Provides explicit timing: 'Call this before any high-risk agent action.' The action-to-tier mapping gives context for when to use. However, it does not explicitly state when not to use or name alternative tools, so it falls short of a perfect score.

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 zero annotations, the description carries the full burden and exceeds it — disclosing the in-memory hash set mechanism, sub-1ms latency, no-network-after-warm behavior, sliding window sizes (3/5/8/10), canonical SHA256 hashing, and the ~300ms first-call warm penalty. It even documents latency_us and cache_size as return diagnostics, giving the agent a complete behavioral model.

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?

Four tight paragraphs with a clean Returns list for machine/agent parsing. Every sentence earns its place — mechanism, usage directive, params, return contract. It borders on verbose for an API description, but the density is justified for the behavioral richness it conveys. The monospaced Args/Returns formatting provides 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?

For a 2-param tool with no output schema, the description covers all the essential bases: what, when, how, parameters, and a complete 7-field Returns section (matched, matched_hash, window_text, window_size, token_offset, latency_us, cache_size). The only gaps are edge behavior, such as what happens with empty input or error conditions, which is a minor omission for an otherwise thorough contract.

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 0%, so the description must compensate — and it does. Both params are documented: text as 'raw, any length' and auto_warm with the crucial cost-benefit note ('adds ~300ms on first call only'). The auto_warm clarification adds genuine value about a performance tradeoff the boolean schema type could never convey. Slight deduction because this critical info is embedded in prose rather than structured, making it easier for an agent to miss.

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 'Check a prompt or text fragment for known PROMPT IOC patterns' — a precise verb+resource+domain statement. 'This is the primary real-time prompt injection detection endpoint' explicitly positions it against the sibling check_prompt_batch, distinguishing it as the real-time variant. No ambiguity about what this tool does.

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 an explicit directive: 'Call it on every user-supplied prompt before passing to the LLM.' The phrase 'primary real-time... endpoint' implicitly differentiates from the batch sibling, but it never explicitly names check_prompt_batch as the alternative or states when NOT to use this tool, leaving the when-vs-batch guidance slightly implicit.

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 disclosure burden. It does disclose the return behavior ('One result dict per input text, in the same order'), which is useful. However, it omits any mention of side effects (if any), error handling, or constraints like batch size limits. For a non-destructive check operation, the lack of explicit safety statements is a gap, but not a contradiction.

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 compact and front-loaded: purpose in first sentence, usage rationale in the second, then Args and Returns. Every sentence adds value—no filler. The structure is clean and easily scannable for an agent.

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 the tool's simplicity (one parameter, no nested objects, output schema present), the description covers purpose, usage, parameter meaning, and return structure adequately. It lacks explicit limitations (e.g., maximum batch size) or error behavior, but for a straightforward batch check, it is sufficiently complete.

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 defines 'texts' as a required array of strings. The description's Args section restates 'List of prompt strings to check', adding minimal new meaning beyond the schema. Since schema coverage is 0% by metric but the param is straightforward, a baseline score of 3 is appropriate given the schema's clarity and the description's confirmation.

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 clearly states 'Check multiple prompts for PROMPT IOC patterns in a single call.' It uses a specific verb (Check), identifies the resource (multiple prompts), and specifies the pattern (PROMPT IOC). This distinguishes it from the sibling tool 'check_prompt' which handles a single prompt.

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 explicitly contrasts with check_prompt() in a loop and explains the efficiency benefit (amortized tokenization and shared cache reference). This directly tells the agent when to use this tool over the alternative, fulfilling the usage guidance dimension fully.

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 well: it explains the mutating drain behavior, the default clearing, the peek option, and the independence of subscriptions. It also documents all return fields, including whether the background push is active, which is useful runtime information.

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 tight and well-structured, opening with a one-sentence summary followed by clear Args and Returns sections. Every sentence earns its place, with no filler or repetition.

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 there is no output schema, the Returns section is essential and well-accounted for. The tool's behavior, parameters, side effects, independence property, and response surface are all covered, making it fully usable for a consumer of a stateful subscription API.

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 0%, but the description fully compensates by explaining both parameters: subscription_id is the output of subscribe_threats(), and drain defaults to true with an explicit peek use-case. This adds meaningful semantics beyond the bare schema names and types.

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 uses a specific verb ('drain') and resource ('buffer of a stateful subscription'), and explicitly links it to subscribe_threats(). It distinguishes itself from sibling tools by explaining it returns IOCs delivered since the last drain and that subscriptions are independent.

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 clearly states this tool is for draining a buffer created by subscribe_threats(), giving concrete context for when to use it. It does not explicitly name exclusionary alternatives like get_new_threats, but the stateful subscription context is enough to guide selection.

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 present, so the description must carry the transparency burden. It communicates an exact-match family name semantics, result limiting, and default value, which is helpful. However, it does not disclose behavior for unknown family names, authorization requirements, or potential error conditions, leaving an edge-case gap.

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 concise and well structured, with a clear one-sentence purpose, a practical prerequisite hint, and compact parameter notes. It contains no unnecessary filler or duplication.

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 two-parameter tool with an output schema, the description covers the essential points: output scope, exact family naming, discovery prerequisite, and limit behavior. Return values are additionally covered by the output schema, so this is sufficiently complete.

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 provides only types and a default, but the description adds meaningful detail: family_name must be exact and includes concrete examples, while limit is given a numeric range and default. Both parameters receive useful semantic context beyond 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 clearly states the tool's purpose: returning all threat signatures for a known malware family. It uses a specific verb and resource, and the distinction from list_families is 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?

The description explicitly instructs the agent to call list_families() first to discover valid family names, which provides clear usage context. It does not discuss exclusions or when alternative threat-lookup tools should be preferred, so it stops slightly short of full 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?

No annotations are provided, so the description carries the full transparency burden. It does well by describing the analysis behavior, IOC feed checks, default track=True behavior, stored baseline/drift logic, and the returned verdict fields. It does not fully explain whether tracking itself writes persistent state or whether IOC feed checks involve external calls, but these are relatively minor gaps.

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 long but well-organized: overview, behavioral details, Args, and Returns. Every section contributes necessary context, and there is no fluff. It is slightly dense because it enumerates many return fields, but that is justified by the lack of an output schema.

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 the tool's complexity, the absence of annotations, and the lack of an output schema, the description is highly complete. It covers the tool's purpose, detection categories, parameter semantics, optional tracking behavior, and all important return fields including risk, score, block/warn flags, signals, IOC matches, latency, and drift.

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 input schema provides names and defaults but no descriptions, and schema coverage is 0%. The description fully compensates with an Args section that explains each parameter: tool_def with expected keys, registry with valid source values, and track with its behavioral meaning. This gives an agent the semantics needed to build a correct call.

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 clear, specific action: 'Analyze an MCP tool definition for instruction-injection and malicious patterns.' It then lists concrete detection targets such as credential exfiltration, C2 callbacks, base64 payloads, authority spoofing, and injection phrases, which makes the tool's purpose unmistakable and distinguishes it from sibling tools that scan content or manage threat feeds.

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 implied: the user should call this when they have an MCP tool definition and need a malicious-pattern/risk analysis. However, the description does not explicitly state when to use this tool vs alternatives such as check_prompt, scan_skill_content, or validate_skill, nor does it mention exclusions or preferred sibling 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?

With no annotations, the description carries the full burden. It discloses relevant behavior: it returns configured limits, shows max staleness, warn threshold, and tier-to-action mapping. It does not explicitly state side-effect-free/read-only, but 'Return' and 'Shows' strongly imply a query operation.

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?

Three short sentences with the main action front-loaded. Every sentence adds useful information: what the tool returns, what fields are included, and how to use the result.

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 zero-parameter configuration query with no output schema, the description is complete. It explains the return contents and connects them to the check_freshness tool, which is exactly what an agent needs to decide when to invoke it.

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 has zero parameters, so the baseline is 4. The description adds value by clarifying that the scope is 'all action tiers' and that the result is about the full configuration rather than a filtered subset.

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 uses a specific verb and resource: 'Return the configured IOC freshness limits for all action tiers.' It clearly states the output scope and differentiates this from runtime check tools like check_freshness by focusing on configuration values.

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 explicitly says 'Use this to understand when check_freshness() will warn or block,' giving a clear use case. It does not explicitly mention when not to use it or list alternative tools, but the context is clear enough.

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?

Although annotations are not provided, the description offers substantial behavioral information: it explains the zero-polling mechanism, the server-side buffering, and the effect of the drain parameter (clearing vs peeking). However, it does not mention potential side effects like blocking behavior, error conditions, or rate limits, so full transparency is slightly limited.

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 concise and well-structured, using bullet points for parameters and returns. It avoids unnecessary fluff and directly conveys the tool's purpose and usage. The format is easy to parse and understand.

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?

The description provides context about the push subscription, the buffer, and lists the return fields (signatures, count, buffered, push_active). It is fairly complete for a tool definition, though it does not elaborate on error handling or edge cases. Given the lack of an output schema, the return list is helpful and covers the expected outputs adequately.

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 only parameter, 'drain', is fully described in the description: it defaults to true and its behavior is clarified (clears buffer when true, peeks without consuming when false). This satisfies the parameter semantics dimension completely.

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 clearly states that the tool drains a live push-subscription buffer of threats, using a verb 'drain' that is specific to the action. It distinguishes itself from poll_since by highlighting zero-polling and server-side buffering via WebSocket subscription. The resource (threat buffer) and the operation are well-defined.

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 explicitly recommends using this tool instead of poll_since when sub-second latency is needed and when the user does not want to maintain a WebSocket connection. This provides clear guidance on when to choose this tool over a named alternative, fulfilling the usage guideline criteria.

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 behavioral burden. It clearly signals a read-only reporting operation ('Return') and lists the visible output data. It does not mention data freshness or authentication, but for a zero-parameter stats tool this is adequately transparent.

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 two short sentences with no filler. The first sentence states the operation and scope, and the second lists the returned metrics. Every sentence earns its place.

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 simple, zero-parameter tool with no output schema, the description is nearly complete: it names the tool's purpose and all returned metrics. It could be slightly stronger by clarifying semantics like time ranges or how 'active agents' is defined, but these are minor gaps for this 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?

The tool has zero parameters, so the baseline score of 4 applies. The input schema already documents this fully, and the description correctly adds no unnecessary parameter details.

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 uses a specific verb+resource pair ('Return aggregate statistics for the threat intelligence database') and enumerates the exact metrics returned (total signatures, malware families, active agents, detection events). This clearly distinguishes it from sibling stats-oriented tools like registry_monitor_stats and prompt_cache_stats.

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 implies use when database-wide aggregate statistics are needed, but it does not explicitly discuss when to use this tool over alternatives or provide exclusion criteria. With multiple sibling stats tools, some direct comparison would improve 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions performance ('O(1) in-process lookup'), which implies a non-destructive, fast read operation. It also specifies the return format: 'revoked: bool, event: Revocation event details if revoked, null otherwise.' This gives the agent expectations about the response. It does not discuss side effects (likely none) or authentication, but for a read-only check, this is sufficient.

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 concise, structured with clear 'Args' and 'Returns' sections, and every sentence adds value. It avoids redundancy and presents the necessary information in a scannable manner. The use of code formatting for the parameter definition enhances readability.

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 the simplicity of the tool (one parameter, no output schema), the description is complete. It explains the purpose, when to use it, the parameters, and the return value. The tool's behavior is well-specified, and nothing critical is missing for the agent 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?

The schema only says 'Value Hash' with no explanation, but the description adds crucial detail: 'value_hash: SHA256 of {ioc_type}:{value.lower()}.' This tells the agent the exact format required, which is essential for correct invocation. Since schema coverage is 0%, the description fully compensates and goes beyond the schema's minimal information.

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 clearly states the tool's purpose: 'Check whether an IOC has been revoked.' It identifies the resource (IOC) and the action (check revocation status), and it differentiates from siblings like 'check_freshness' and 'lookup_ioc' by focusing specifically on revocation. The inclusion of 'O(1) in-process lookup' adds performance context, further clarifying its specific role.

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 provides explicit when-to-use guidance: 'Use this before acting on any cached threat intelligence to ensure the IOC has not been retracted since it was loaded.' This clearly states the intended context and purpose. However, it does not mention when not to use it or suggest alternatives, though siblings are available. The lack of exclusions leaves room for ambiguity, but the primary usage is well-communicated.

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 provided, the description must disclose all behavioral traits. It explains the return content (family name, description, category) and implies a read-only operation, but it does not explicitly state side-effect freedom or any rate limits. This is minimal but adequate for a simple list operation.

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 two sentences long, front-loads the core action, and efficiently adds field details and a cross-reference to a sibling tool. Every word earns its place.

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 the tool's simplicity (0 params, existing output schema), the description covers what it returns and how to proceed to IOCs. It might have mentioned if results are ordered or limited, but for a basic list operation, it is complete enough.

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 has zero parameters, and per the rubric, baseline is 4. The description adds no parameter information (unnecessary) but also doesn't introduce any ambiguity. Schema coverage is trivially 100%.

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 clearly states 'Return all known malware families in the intelligence database' with a specific verb and resource. It distinguishes itself from 'family_threats' by noting that the latter retrieves IOCs for a family, making this the listing 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?

The description explicitly points to 'family_threats(family_name)' as the next step to get IOCs, providing a clear alternative for related functionality. While it doesn't list every possible alternative among siblings, it gives practical usage context for a list-then-detail pattern.

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 transparency burden. It discloses ordering ('newest first'), filtering behavior ('since_hours' with 0 meaning no time filter), and return semantics ('all retained'). It does not detail pagination or retention limitations, but for a list tool this is reasonably transparent.

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 compact and well-structured: a one-sentence purpose, then Args and Returns sections. Every line contributes meaning, and the front-loaded verb phrase makes the tool's purpose immediately clear. No filler or redundancy.

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 the tool's simplicity, two optional parameters, and no output schema, the description is complete. It documents each parameter's behavior and all three return components ('revocations', 'total', 'stats'), so an agent can invoke and interpret results without additional 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 description coverage is 0%, so the description fully compensates by explaining both parameters: 'limit' is the maximum number to return (default 50), and 'since_hours' filters to revocations newer than N hours with 0 meaning no time filter. This goes well beyond the schema's bare type/default declarations.

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 'List recent IOC revocations, newest first,' which is a specific verb+resource statement that clearly identifies the tool's function and output ordering. This distinguishes it from sibling tools like revoke_ioc (which performs a write) and is_ioc_revoked (which checks a single IOC).

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 to use the tool—when you need recent revocation events—and explains the two filtering parameters with their defaults. It does not explicitly mention exclusions or alternatives, but the list vs. check vs. revoke distinction is apparent from the wording.

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 burden. It states that it returns metadata, not the buffered IOCs themselves, which is a useful behavioral detail. However, it doesn't mention any side effects (though listing is likely read-only), performance considerations, or pagination. For a simple list operation, this is adequate but not excessive. It doesn't contradict annotations (none exist).

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 concise and to the point: first sentence states the purpose clearly, second sentence clarifies output content and usage context. No wasted words. Perfectly structured for quick comprehension.

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 tool with zero parameters and an output schema present, the description is sufficient. It explains what is returned (metadata) and what is not (buffered IOCs), which contextualizes the output. It could mention if there are any filters or ordering, but given no params, it's likely a simple listing tool. It doesn't need more detail.

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 has no parameters, so the description doesn't need to explain any. The schema coverage is 100% (vacuously). The description adds value by clarifying what the tool returns (metadata) and what it doesn't (the actual buffered IOCs), which helps interpret the output schema context. For a zero-parameter tool, a baseline of 4 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?

The description clearly states the tool's purpose: 'List all active stateful push subscriptions on this MCP server instance.' It specifies the resource (subscriptions), scope (active stateful push), and distinguishes it from siblings by noting it returns metadata, not the buffered IOCs themselves. This is a specific verb+resource+scope that differentiates it from related tools like subscribe_threats and unsubscribe.

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 provides a usage context: 'Useful for inspecting what agents are currently subscribed and what filters they have configured.' This indicates when to use it but does not explicitly mention alternatives or when not to use it. Compared to siblings, it's clear this is for introspection rather than action, but the absence of explicit exclusions 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?

With no annotations, the description carries the full burden for behavioral disclosure. It states that the full signature record is returned if found and lists included fields, which is useful, but it does not describe behavior when the IOC is not found, such as returning null or raising an error, nor does it state that this is a read-only operation.

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 concise and well-structured: a clear first sentence stating the purpose, a second sentence summarizing the return value, and a short Args section for the parameter. Every line adds necessary information with no redundancy.

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 simple single-parameter lookup tool with no output schema or annotations, the description adequately covers purpose, return contents, and parameter semantics. It falls short only by not specifying the not-found response, which would make it fully complete.

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 only provides the parameter name and type, but the description adds meaning by explaining that the value must be the exact IOC and gives an example ('evil.example.com'). This is sufficient for a single string parameter, though it could add details like case sensitivity or expected formatting.

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 uses a specific verb and resource: 'Look up a threat signature by its exact IOC value.' It clearly distinguishes from sibling tools like search_by_type by emphasizing exact IOC lookup, making the tool's purpose unambiguous.

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 phrase 'by its exact IOC value' implies the tool should be used when the caller has a specific IOC and needs the full signature, conveying when to use it. However, it does not explicitly mention alternatives or state when not to use this tool versus sibling tools like search_by_type or is_ioc_revoked.

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 provided, the description carries the full burden of behavioral disclosure, and it delivers: it reveals that no persistent connection is required, that state must be persisted between calls (next_id), that the tool batches results, and that immediate re-calling is needed to drain the backlog. This is exactly the kind of behavioral context an agent needs for a stateful sync operation.

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 efficiently structured: a purpose sentence, a pattern statement, a usage flow, and a compact Args block. Every sentence earns its place — the 'No persistent connection required' note and the drain instruction are behaviorally significant, not filler. There is no repetition of schema information, and the content is front-loaded with the core 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?

Given this is a stateful pagination tool with no annotations and no output schema, the description covers the critical operational details: first-run initialization, state persistence, backlog draining, and parameter ranges. The only minor gap is that the min_severity 0–10 scale's meaning is left to the agent's inference (does higher mean more severe?), and the next_id return contract is implied rather than explicit.

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 0%, so the description must fully compensate, and it does. It adds substantive meaning beyond the schema's bare defaults: last_id is explained as the high-water mark to persist between calls, batch_size gets a valid range (1–5000) and semantics ('max signatures to return'), and min_severity gets a range and behavior ('skip signatures below'). This directly enables correct parameter usage.

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-resource-scope construction: 'Fetch new threat signatures since a high-water mark ID.' This clearly identifies the tool's function and differentiates it from siblings like get_new_threats (bulk retrieval) and check_freshness (status check) by emphasizing the incremental high-water mark pattern and explicitly labeling it 'the recommended sync pattern.'

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 strong usage guidance: call with last_id=0 on first run, persist next_id, pass it on subsequent calls, and drain backlog when count == batch_size. It explicitly states this is 'the recommended sync pattern' versus a persistent connection. However, it doesn't name specific sibling alternatives or state when NOT to use this tool, stopping just short of the explicit when/when-not standard.

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 must carry the behavioral burden. The word 'Return' implies a read-only operation, which is appropriate for a stats tool, but it does not explicitly state read-only, side-effect-free behavior, or any authentication/permission requirements. The mention of 'refresh status' describes cache state, not tool behavior, adding only marginal transparency.

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?

Two sentences, both front-loaded and purposeful. The first states exactly what the tool does, and the second provides actionable usage context. No filler or redundancy.

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 simple, parameterless stats tool, the description is nearly complete with purpose, metrics, and usage context. It lacks an explicit return-value format (e.g., whether stats are integers, floats, or nested objects), but the named fields offer sufficient grounding. The sibling relationship to check_prompt adds workflow 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?

The tool has zero parameters, and the schema is empty, which makes parameter explanation unnecessary. The description instead enumerates the statistics returned, which is useful context even though it is not strictly parameter semantics. Per the rubric, a zero-parameter tool receives a baseline of 4.

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 'Return' and identifies the resource as 'PROMPT IOC cache statistics' with concrete metrics: size, hit rate, latency, refresh status. This clearly distinguishes it from sibling stats tools like get_stats and registry_monitor_stats by focusing on the prompt cache specifically.

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 explicit context: 'Use this to verify the cache is warmed and healthy before relying on check_prompt() for real-time detection.' It names a dependent tool (check_prompt) and establishes a clear sequencing relationship, though it does not mention when not to use it or list 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?

Annotations are absent, so the description carries the disclosure burden. It communicates a read-style operation, temporal ordering, and parameter ranges, but does not mention time windows, pagination, auth requirements, or absence of side effects.

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 compact and scannable, with a one-sentence purpose followed by a two-line parameter list. Every sentence contributes new information without redundancy.

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 simple read tool with two optional parameters and an output schema, the description covers purpose and parameter semantics well. It only lacks explicit placement relative to sibling tools and a note on any operational constraints, preventing a top score.

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 Args block enriches both schema properties: limit gets a 1-200 range and min_severity gets a 0-10 scale with default 5 meaning 'medium+'. This adds meaning beyond the bare type/default entries in the input 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 opening sentence 'Return the most recently observed threat signatures' uses a specific verb and resource with a temporal scope. This clearly differentiates the tool from siblings like family_threats and search_by_type by specifying recency.

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?

No explicit when-to-use or when-not-to-use guidance is provided, and no sibling alternatives are mentioned. The recency framing only weakly implies a retrieval scenario, and potential overlap with get_new_threats is unaddressed.

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 provided, the description carries the full burden for behavioral disclosure. It does add useful context about the two flag categories: high-risk fingerprinting on ingestion and semantic drift on update. However, it does not mention whether the list is live, cached, or ordered, nor whether it includes revoked or false-positive entries. This is adequate but not rich for a security-related registry 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?

The description consists of two concise sentences with no wasted words. The first sentence states the primary purpose, and the second identifies the inclusion criteria. All content adds value and the structure is easy to parse quickly.

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 that the tool has zero parameters, an output schema exists, and the full scope is 'all tools flagged' with explicit mention of both reporting-flags categories, the description is complete. It tells the agent the exact universe of results without needing further mention of filtering, return value formatting, or side effects.

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 input schema has an empty properties object, so there are no parameters to clarify. The description therefore does not need to add parameter-level semantics. The baseline of 4 for zero-parameter tools 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?

The description opens with a direct and specific statement: 'Return all MCP tools that have been flagged as suspicious or malicious.' This clearly identifies the action, resource, and scope. The second sentence adds distinguishing detail by identifying the two categories of flags included, helping differentiate it from sibling threat-listing tools.

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 does not provide guidance on when to use this tool versus the many related siblings such as recent_threats, get_new_threats, or fingerprint_tool_metadata. There are no exclusions, alternatives, or contextual cues about a preferred use case. The inclusion criteria are stated, but they do not operationalize the decision of when this tool is the right one.

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 provided, the description carries the full burden of disclosing behavior. It clearly identifies the output metrics and implies a read-only monitoring operation, but it does not explain whether the statistics are computed live, whether any side effects occur, or how 'drift detection rate' is derived.

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 two sentences, immediately states the purpose, and lists the three key metrics without any fluff. Every sentence earns its place.

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 zero-parameter, no-output-schema statistics tool, the description covers the essential information: what the tool does and what data it exposes. It lacks minor details like value types or units for the drift detection rate, but overall it is reasonably complete for the tool's simplicity.

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 input schema has no parameters, so the baseline is 4. There is nothing for the description to add about parameter semantics, and it correctly avoids inventing any.

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 uses a specific verb ('Return') with a clear resource ('MCP registry monitoring statistics') and enumerates the exact metrics provided (tracked tools, flagged tools, drift detection rate). This specificity distinguishes it from the sibling 'get_stats' tool, which covers broader statistics.

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?

No guidance is given about when to use this tool instead of related siblings like 'registry_flagged_tools' or 'get_stats'. The description only states what it returns, with no context on appropriate scenarios or exclusions.

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 burden of disclosing side effects. It explicitly states that the tool increments the signature's detection count and creates a ThreatEvent visible to all other agents in real-time. This is meaningful behavioral context beyond the parameter schema, though it does not mention authentication, reversibility, or error conditions.

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 compact and well-structured: a one-sentence purpose, a one-sentence behavior summary, and a clearly formatted Args block. Every sentence contributes meaningful information with no filler or redundancy.

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 3-parameter tool with no annotations and no output schema, the description covers purpose, side effects, and parameter semantics adequately. It does not describe return values or failure modes, but the primary behavioral consequences are disclosed, making it sufficiently complete for an agent to invoke 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 0%, and the description fully compensates by explaining all three parameters: signature_id as the ThreatSignature ID from submit_ioc/lookup_ioc, action with the allowed enumerated values, and context as an optional dict with examples. This adds real semantic value beyond the bare JSON 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 clearly states the action: 'Report that you detected and acted on a known threat signature.' It names the specific resource (report_detection), identifies the mechanism (increments detection count, creates ThreatEvent), and is sharply distinguished from siblings like submit_ioc or vote_false_positive by the reporting semantics.

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 phrase 'Report that you detected and acted on a known threat signature' establishes a clear usage context. It also directs signature_id sourcing from submit_ioc or lookup_ioc, implying the workflow. It does not explicitly name alternatives or exclusions, but the guidance is sufficient for a straightforward reporting tool.

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 full burden. It discloses the real-time push to active subscriptions, the subscriber-facing event_type='revocation', and the return fields (event, pushed). It does not cover error cases, idempotency, or permissions, but the key behavioral side effects are clearly described.

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 a front-loaded action, a when-to-call note, and clearly labeled Args and Returns sections. Every sentence adds value and there is no repetition or 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 mutation tool with no annotations and no output schema, the description covers the essential context: parameter format, reason enums, subscription side effects, and return values. Minor gaps remain around error conditions and whether revocation is idempotent or reversible, but the description is largely complete for an agent to use 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 0%, so the description compensates thoroughly. It explains value_hash's exact format (SHA256 of {ioc_type}:{value.lower()}), lists all valid reason values, and clarifies that ioc_type is optional for subscriber filtering. It even provides provenance for obtaining value_hash from list_revocations() or the threat signature record.

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 'Revoke' + resource 'IOC' + method 'by its value hash' and adds behavioral detail ('pushing the expiration event to all active subscriptions in real-time'). This clearly distinguishes it from siblings like is_ioc_revoked (check) and list_revocations (list).

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 when to call: 'when an IOC is determined to be a false positive, expired, or superseded.' It also explains the downstream effect on subscribers via drain_subscription(). It does not mention when not to use it or reference alternative tools, but the when-to-use is unambiguous.

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 zero annotations provided, the description carries full weight, and it delivers. It explains the behavioral contract: what gets scanned ('skill/instruction files'), what to do with the result ('refuse to proceed' on block), and crucially WHY this matters (the CodeMax attack class, 2026-03-14). The detection signals section is a veritable behavioral spec, mapping categories (credential access, code obfuscation) to concrete patterns. It doesn't just describe the tool; it describes the security implications.

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 exceptionally well-packaged: a one-sentence summary, a security-relevant contextual paragraph, a list of detection signals, and one-line arg/return documentation. It's front-loaded with the most critical instruction (call this before executing) and uses bullet points for scrutability. Every sentence contributes to the agent's decision-making; the only potential nitpick is the security paragraph being slightly verbose, but it's justified as it adds critical context.

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?

This is an unusually rich description for a security-scanning tool, combining purpose, usage, signals, and return contract. The output schema is missing, so documenting the return structure (risk, risk_score, should_block, etc.) adds value. It covers the agent's need to understand side effects (none given, but 'refuse to proceed' is explicit). Minor deductions for omitting the default behavior of source_url and edge cases (what about extremely large content?).

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 0%, so the description has to define both parameters, and it does: content is 'Full text content of the skill file', source_url is 'URL where the skill was fetched from (for reporting)'. This is beyond the basic property names. However, it doesn't add crucial edge-case semantics—like whether content is truncated or handled for encoding—and given only 2 simple string params, it's not a major gap. Mostly sufficient because the parameters are self-evident.

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 uses a specific verb-resource pairing ('Analyzes the full text of a skill... for malicious patterns') and clearly distinguishes this tool from siblings by emphasizing it's the 'critical defense' against skill-mediated attacks. The context about executing before the agent follows instructions, combined with the explicit 'if should_block is True, refuse to proceed' action item, leaves no doubt about the tool's scope. This is clearly differentiated from sibling tools like 'validate_skill' or 'submit_ioc'.

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 is explicit: 'Call this on any skill/instruction content fetched from the web before executing any of its steps.' It doesn't just imply when to use it—it gives the exact context (web-fetched content), a conditional action ('if should_block is True, refuse to proceed'), and an implicit exclusion by omission of cases where it shouldn't be used. The instruction 'After fetch, before exec' is repeated for emphasis, leaving little room for an agent to misfire.

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 burden of behavioral disclosure. It communicates that this is a read-only, filtered retrieval and documents the limit and severity defaults, but it does not mention sorting, pagination, result size caveats, or any operational constraints beyond the parameter ranges.

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 compact and front-loaded with the core purpose, followed by a terse argument list. Every line adds necessary information, and the examples support comprehension without 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?

Given the presence of an output schema and only three simple parameters, the description is largely complete: it defines all parameter semantics and defaults. It could slightly improve by noting how to choose this over sibling search-like tools, but overall it provides enough context 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?

Input schema description coverage is 0%, but the description fully compensates by enumerating all valid ioc_type values, specifying the 1-1000 range for limit, and defining min_severity range and default behavior. This adds substantial meaning beyond the raw JSON 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 'Return threat signatures filtered by IOC type,' which clearly names the verb, resource, and filtering scope. The examples of known-bad IPs, malicious domains, and AI skill hashes help distinguish it from sibling tools like lookup_ioc or recent_threats.

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 phrase 'Useful for pulling all known-bad IPs, all malicious domains, all malicious AI skill hashes, etc.' provides clear use cases. It does not explicitly name alternatives or when-not-to-use conditions, but the context is sufficient for an agent to select it appropriately.

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 present, so the description carries the behavioral burden. It does disclose useful behavior: each dict must have 'ioc_type' and 'value', and results are returned per input in the same order. However, it does not mention failure semantics, partial batch behavior, rate limits, or size limits, which are significant for a batch mutation 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?

Every sentence adds value: purpose, use case, parameter contract, and return behavior. It is compact, front-loaded, and free of 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 single-parameter batch tool with an output schema, the description covers the key contract: what each item must contain, what is optional, and the ordered per-item response. Missing details like batch size limits and error handling prevent a perfect score, but the core usage is complete.

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 input schema only defines 'iocs' as an array of objects with additionalProperties true, giving almost no meaning. The description compensates well by specifying required keys, optional keys, and the mapping to submit_ioc parameters. It stops short of fully defining each optional field's semantics, so not a 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?

Description opens with a specific verb+resource: 'Submit multiple IOCs in a single call.' It clearly distinguishes itself from the sibling submit_ioc by explicitly positioning itself as the bulk alternative and stating the use cases.

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 when to use it ('Preferred over looping submit_ioc for bulk ingest from honeypots, sandboxes, or feed processing') and names the alternative (submit_ioc). This gives an agent clear decision context.

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 full burden. It discloses that the IOC is auto-classified, metadata is compressed, deduplication is atomic, and all subscribed agents see it instantly. It also notes that family_hint can skip auto-classification. This provides useful side-effect context, though it doesn't cover failure modes or rate limits.

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?

Two paragraphs: an intro that adds behavioral context and a structured Args list. Every sentence contributes value, with no fluff. The list format is scannable and appropriately sized for the parameter count.

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 complex tool with 8 parameters and no output schema, the description covers all parameters thoroughly, explains the processing pipeline, and notes the optional family_hint. It provides complete contextual information for an agent to select and invoke 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?

The description includes an Args section that fully documents all 8 parameters with types, allowed values, and examples. Since schema description coverage is 0%, this completely compensates for the lack of schema descriptions, providing detailed semantics for each field.

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 clearly states 'Submit a threat indicator (IOC) to the shared intelligence network' - a specific verb and resource. It distinguishes from siblings like submit_batch (batch submission) and lookup_ioc (lookup) by focusing on single IOC submission with automatic 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?

The description implies usage for submitting a single IOC but does not explicitly mention when to use it versus alternatives like submit_batch. No exclusions or contraindications are provided. Usage context is implied by the verb 'submit' and the resource type, but no direct comparison to sibling 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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses statefulness, subscription expiry, independent copies per subscriber, zero-polling behavior, and the need for SSE mode. The Returns section transparently lists subscription_id, push_active, and filters.

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 a clear opening, filter bullet list, prerequisites, and a Returns block. Every sentence adds value—no filler or repetition beyond what is useful for agent understanding.

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 stateful subscription tool with 4 parameters and no output schema, the description is complete. It covers lifecycle (expiry, drain), isolation semantics, parameter meanings, required infrastructure, and return values, making it sufficient for an agent to invoke 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 0%, but the description fully compensates. It explains min_severity as 0-10 with default 5 (medium+), defines each filter's empty=all behavior, provides an example for ioc_types, and lists all valid IOC type values. This exceeds the schema's bare array definitions.

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 'Open a named, stateful subscription to live threat push delivery,' which clearly identifies the verb, resource, and the stateful streaming nature. It distinguishes itself from sibling polling tools like get_new_threats and poll_since by emphasizing 'zero polling' and the subscription lifecycle.

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 provides clear context for when to use this tool: for live push delivery, with each caller getting an isolated stream and subscriptions expiring after 1 hour of inactivity. It also states the explicit prerequisite of SSE mode and a live SpacetimeDB push subscription, but does not name specific alternatives to avoid, so it stops short of a full 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?

Since no annotations are provided, the description carries the full burden. It discloses that subscriptions auto-expire, and the return status indicates if it was already removed. It doesn't mention any side effects beyond free memory, but that's sufficient for a simple cancellation 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?

The description is concise with clear sections for args and returns, using short sentences. Every sentence adds value without unnecessary fluff.

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?

The tool is simple with one parameter, and the description covers purpose, usage, and return values. It doesn't mention any specific errors beyond 'not_found', but that's adequate for this simple 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 0% for the single parameter, but the description clarifies that subscription_id is the ID returned by subscribe_threats(), adding important source context. However, it doesn't add format or validation details, so it partially compensates.

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 clearly states it cancels a stateful subscription and frees its buffer, using a specific verb and resource. It distinguishes from siblings like subscribe_threats and drain_subscription by focusing on cancellation and memory release.

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 when to call ('when you no longer need the subscription to release memory') and notes auto-expiry after 1 hour, which helps the agent decide when manual unsubscription is necessary versus relying on automatic cleanup.

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?

Even with no annotations to support it, the description transparently discloses the synchronous nature, the decision logic (allow/warn/block based on known-malicious hash), and the informational fields it returns. It could be richer about side effects like logging or external calls, but it largely carries the burden well.

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 clear sections for arguments and return values, each with no wasted words. Every line adds value, and the format is easily scannable.

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 wisely documents all return fields (risk, action, confidence, signature_id, family_name, reason), making the tool self-contained. It loses one point for not covering edge cases like error behavior or rate limiting, but it is otherwise sufficient for an agent to use it effectively.

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 0%, but the description fully compensates by explaining each of the 3 parameters, including their preferred usage ('preferred identifier' for skill_hash, 'for logging' for skill_name, and 'fallback if hash unknown' for manifest_url), going beyond the schema's type-only definitions.

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 clearly states this is a 'Synchronous SKILL IOC lookup' and explicitly instructs to 'call this before loading or invoking any MCP tool/skill', which distinguishes it from siblings like check_freshness or lookup_ioc. The resource (skill) and action (validate against a threat feed) are unambiguous and specific.

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 timing ('before loading or invoking'), a clear use case ('pre-invocation enforcement hook'), and distinguishes the identifier hierarchy (hash preferred, URL fallback). However, it doesn't explicitly mention when not to use it or contrast with a direct alternative, which would fully earn 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?

With no annotations, the description carries the burden. It discloses the effect (sets is_likely_fp to True after threshold) and the purpose (signal to review before blocking), but does not mention side effects like whether the vote is reversible or if there are permission requirements.

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 concise, using two sentences to cover the action, condition, and parameters. No unnecessary fluff, well-structured for quick comprehension.

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 the simple nature of the tool, the description covers its purpose, parameters, behavioral outcome, and the threshold condition. There is no output schema, so not needing to explain return values is acceptable. The description is fully sufficient.

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 has 0% description coverage, but the description fully defines both parameters: signature_id as the ID of the threat signature, and reason as an optional explanation. This adds complete meaning to the parameters.

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 clearly states the action (flag a threat signature as a likely false positive) and the specific resource (threat signature). It also explains the voting mechanism and the resulting condition, distinguishing it from other security tools.

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 explains when the tool is used (to cast a vote that may trigger a flag after 20% threshold) but does not explicitly contrast with alternatives or state exclusions. It implies the purpose well enough for an agent to select it correctly.

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 behavioral disclosure burden. It explains that the operation loads data into an in-memory hash set, eliminates network access for subsequent checks, and auto-refreshes every 5 minutes in the background. This is substantive behavioral context beyond the tool name.

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 tightly structured: a one-sentence purpose, a short usage note, and a clean Returns list. No filler or redundancy exists, and every sentence adds meaningful 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?

Given zero parameters, no output schema, and no annotations, the description fully covers the tool's purpose, invocation timing, performance implications, auto-refresh behavior, and return values. There is no obvious gap for an agent 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?

The tool has zero parameters, so the baseline is 4. The description appropriately focuses on the return fields (loaded, duration_ms, window_sizes) instead of parameter details, which would be irrelevant here.

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: 'Load all PROMPT IOCs from SpacetimeDB into the in-memory hash set.' This clearly identifies the tool's function and distinguishes it from siblings like check_prompt and prompt_cache_stats, which query or inspect the cache rather than populate it.

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 guidance is explicit: 'Call once at startup (or after a major feed update)' and notes that subsequent check_prompt() calls require no network access. This gives clear when-to-use context, though it does not explicitly name alternative tools or state when not to use it.

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