Nullcone Threat Intelligence

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 reveals that the check completes in <1ms with no network I/O, explains the block_on_stale behavior (returns an error dict as a hard block), and defaults to warn-only. This is thorough and sets correct expectations for a validation 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 well-structured and front-loaded with purpose. The tier mapping is presented in a compact, scannable format, and every sentence serves a purpose: purpose, usage timing, latency, parameter semantics, and return values. No wasted words.

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 output schema and no annotations, the description is exceptionally complete. It lists all return fields, explains default behavior for both parameters, defines tier limits, and even notes the latency. For a relatively simple 2-param tool, this is a fully self-contained specification.

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 description coverage is 0%, but the description fully compensates. The 'action' parameter is explained through the tier mapping, including how unknown actions default to HIGH. 'block_on_stale' is clearly defined with its True/False behavior and default. This adds substantial meaning beyond the sparse schema fields.

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: 'Validate that IOC threat intelligence is fresh enough for the named action.' This clearly distinguishes it from siblings like freshness_limits (which likely returns limits) and get_stats (which aggregates stats). The purpose is unambiguous and action-oriented.

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 states when to use the tool: 'Call this before any high-risk agent action to ensure the TI snapshot is not stale.' It also provides a detailed action-to-staleness-tier mapping, giving the agent concrete decision criteria. This goes beyond mere context and effectively guides tool 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?

With no annotations provided, the description fully discloses behavior: it uses an in-memory hash set, performs token-window sliding at sizes 3/5/8/10, checks canonical SHA256 hashes, and auto-warms on first call adding ~300ms. It also explains the no-network-after-warm aspect and lists all return fields. This is far beyond what structured data could convey.

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

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

The description is well-organized: opening purpose, mechanism, usage directive, then clearly labeled Args and Returns sections. Every sentence contributes useful content, with no fluff or redundancy. It is appropriately sized given the tool's complexity.

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 has no output schema, so the description lists all six return fields with concise meanings. It also covers performance characteristics and the auto-warm nuance. Combined with the parameter details and usage directive, the description is fully self-contained and actionable for an agent.

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%, yet the description explains both parameters thoroughly: 'text' is 'the prompt text to check (raw, any length)', and 'auto_warm' is described with behavior details ('adds ~300ms on first call only') and its default true. This fully compensates for the lack of schema descriptions.

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

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

The description states exactly what the tool does: 'Check a prompt or text fragment for known PROMPT IOC patterns.' It also identifies itself as the 'primary real-time prompt injection detection endpoint,' clearly distinguishing it from batch and other related tools. The verb+resource combination is specific and 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 description gives clear usage guidance: 'Call it on every user-supplied prompt before passing to the LLM.' It also notes this is the primary real-time endpoint, implying batch alternatives exist. However, it does not explicitly mention when to use a sibling tool like check_prompt_batch or when not to use this tool, so it stops short of a full 'when/when-not' blueprint.

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 transparency burden. It discloses some behavioral traits: returns one result dict per input text in the same order, and mentions efficiency-related internal mechanics (tokenization amortization, shared cache). However, it does not explicitly state whether the operation is read-only or if it modifies any state, nor does it describe error handling 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?

The description is well-structured with a clear opening line, a practical efficiency note, and explicit Args/Returns sections. Every sentence adds value; it is concise without being overly terse. Slight redundancy in the Args section (the parameter is already in schema) but acceptable.

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 has a single parameter, an output schema, and a clear sibling context. The description explains the return format (one result dict per input in order) and the batch benefit. It is complete enough for an agent to invoke correctly, though it could optionally mention that a valid 'prompt' format is expected or what IOC patterns look like.

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 shows 'texts' as an array of strings with no explanation. The description compensates by defining the parameter as 'List of prompt strings to check,' adding domain context. Since schema description coverage is 0%, the description must compensate, and it does effectively for the single parameter.

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 function: 'Check multiple prompts for PROMPT IOC patterns in a single call.' It specifies the verb (check), the resource (multiple prompts), and the scope (PROMPT IOC patterns), and it distinguishes itself from the singular check_prompt tool by explicitly addressing batching.

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 clear guidance on when to use this tool versus check_prompt: 'More efficient than calling check_prompt() in a loop' with a concrete reason (tokenization overhead amortized, shared cache reference). It implies this should be used for multiple prompts, but does not explicitly state when not to use it or alternative conditions.

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 the key side effect: drain=True clears the buffer after returning, while drain=False peeks without consuming. It also notes that subscriptions are independent, which is important for understanding cross-subscription behavior.

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

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

The description is front-loaded with the purpose, then uses compact Args and Returns blocks. Every sentence and field serves a purpose; there is no redundant or promotional language. The structure makes it easy to scan and parse.

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

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

There is no output schema, but the Returns block fills that gap by enumerating signatures, count, buffered, and push_active. The description covers args, behavior, side effects, and return values in a self-contained way for a tool of this 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 description coverage is 0%, so the description must fully explain parameter meaning. It does exactly that: subscription_id is defined as the ID returned by subscribe_threats(), and drain's True/False behavior is clarified including its default. This adds significant value beyond the raw 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 line states the specific action ('Drain the buffer of a stateful subscription') and names the creating tool ('created by subscribe_threats()'), making the tool's role unmistakable. It also clearly distinguishes it from sibling tools like subscribe_threats, get_new_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 clearly scopes usage to subscriptions created by subscribe_threats(), and explains the drain/peek modes via the drain parameter. It does not explicitly name alternatives or exclusion cases, but the context is sufficiently clear for an agent to know when to invoke it.

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 the tool's purpose, the need for an exact family name, and the limit parameter with its range and default. However, it does not mention what happens when a family name is unknown, whether authentication is required, or if results are paginated—leaving some behavioral ambiguity.

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 only three short sections: a one-sentence purpose, a one-line usage instruction, and an Args list. It is front-loaded with the core action and contains no filler, making it highly efficient.

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 two-parameter lookup with an output schema present, the description covers the purpose, prerequisite, and parameter semantics well. It stops short of explaining error behavior or empty-result cases, but given the output schema and the straightforward nature of the tool, it is largely 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 has zero description coverage, so the Args section is essential. It gives concrete examples for family_name ('emotet', 'qbot', 'cobalt_strike') and specifies limit's range (1-500) and default (50). This far exceeds what the bare schema provides.

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 all threat signatures associated with a known malware family,' which is a specific verb+resource combination that clearly distinguishes this from sibling tools like lookup_ioc or search_by_type. It also implies the scope (family-based) and gives a direct action.

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 instructs 'Use list_families() first to discover available family names,' providing an explicit prerequisite and directing the agent to a specific sibling tool. It doesn't formally state when not to use the tool, but the instruction is clear and actionable.

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 disclosure burden. It transparently covers key behaviors: semantic fingerprinting, IOC feed checks, risk scoring, and the stateful drift-tracking mechanism (track=True maintaining a stored baseline). This goes beyond surface-level details.

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 paragraphs, an Args list, and a Returns list. Every sentence adds value, and the front-loaded opening sentence captures the core purpose. Though detailed, it is appropriately sized for the tool's complexity.

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 lack of an output schema, and 0% schema description coverage, the description is impressively complete. It enumerates all return fields, explains risk levels, mentions drift behavior, and specifies input constraints—leaving no significant gaps.

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 Args section fully compensates by explaining each parameter: tool_def with expected keys, registry's allowed values, and track's meaning/default. This gives the agent everything needed to construct valid calls.

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: analyzing MCP tool definitions for instruction-injection and malicious patterns. Specific verbs like 'Analyze' and 'Performs semantic fingerprinting' combined with the resource ('MCP tool definition') make it distinct from sibling tools that handle prompts or skills.

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 implies when to use the tool—whenever an MCP tool definition needs security analysis. It details input expectations and optional flags (track, registry). However, it does not explicitly mention alternatives or exclusions, such as using scan_skill_content for skill files, so it stops short of 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 provided, the description carries the full behavioral disclosure burden. It discloses the return content (max staleness, warn threshold, tier membership) but does not explicitly state that the operation is read-only or free of side effects. For a simple getter, this is minimally adequate but not comprehensive.

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 three concise sentences, each serving a purpose: stating the action, detailing the return content, and offering usage guidance. It is front-loaded and contains no 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 zero-parameter tool with no output schema or annotations, the description fully covers what the tool does, what data it returns, and when to use it. No additional context is necessary given the low 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?

The tool has zero parameters, so the description does not need to explain parameter meanings. Baseline for 0 params is 4, and nothing in the schema or description requires adjustment.

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 returns configured IOC freshness limits for all action tiers, using the specific verb 'Return' and naming the resource. It distinguishes itself from sibling 'check_freshness' by explaining that this tool provides the limits that check_freshness uses to warn or block.

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 usage guidance: 'Use this to understand when check_freshness() will warn or block.' This clearly indicates when to use it and provides context relative to the sibling check_freshness tool, though it doesn't enumerate when-not 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?

No annotations exist, so the description carries full responsibility. It discloses the buffer-draining behavior, the drain parameter's effect, and the return fields including 'push_active' for subscription status. It also communicates the zero-polling push mechanism, which is non-obvious.

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 into concept, usage, and parameters/returns. Each sentence adds useful information with no redundant filler. The Args/Returns block is concise and 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?

Given there is no output schema, the description fully explains all return fields and their semantics. It also covers the drain side-effect and the background subscription status, making the tool behavior completely understandable 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?

The schema provides only a boolean 'drain' with a default, but the description explains its semantics fully: 'If True (default), clear the buffer after returning. Set False to peek without consuming.' This adds essential meaning beyond the bare 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 states a specific action: 'Drain the live push-subscription buffer of threats received since the last call.' It explicitly distinguishes itself by naming an alternative: 'Use this instead of poll_since()...' The verb-resource pairing is clear and unique among siblings.

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

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

Explicit guidance is provided: 'Use this instead of poll_since() when you need sub-second latency without maintaining your own WebSocket connection.' It also explains the architecture (MCP server maintains subscription) and offers an on-demand usage pattern, making the use case clear.

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 full burden. It discloses that the operation returns aggregate statistics, but does not explicitly state that it is read-only or mention any side effects. For a simple stats retrieval, the disclosure is adequate but not rich.

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, front-loaded with the main verb, and every word earns its place. It is efficient and free of redundant information.

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

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

With no output schema, the description must explain return values, and it does by listing the included statistics. The tool's simplicity and zero-parameter schema make this description 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 tool has zero parameters, which is fully captured by the schema. The description adds clarity about what the returned statistics include, which is valuable given no output schema or parameters exist.

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 returns aggregate statistics for the threat intelligence database, listing specific included metrics. It is unambiguous, though it does not explicitly differentiate from other statistics-like sibling tools such as prompt_cache_stats or registry_monitor_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?

No guidance is provided on when to use get_stats versus alternative tools. Given the presence of sibling tools with overlapping statistical purposes, the lack of usage context is a noticeable gap.

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 adds 'O(1) in-process lookup,' revealing performance and no external I/O. It also details the return format (revoked bool, event details). It does not explicitly state that it is read-only or has no side effects, but 'check' and 'lookup' imply this. This is solid but not exhaustive.

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 usage guideline, and an Args/Returns section. Every sentence adds value, with no redundancy or filler. Formatting improves readability and 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 simple one-parameter lookup tool with no output schema, the description covers the purpose, usage context, parameter encoding, and return semantics. It leaves no major gaps for an agent to safely invoke the tool. The O(1) note and hash format are particularly helpful.

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 a string parameter with no description, leaving 0% coverage. The description compensates fully by defining the exact format: 'SHA256 of {ioc_type}:{value.lower()}.' This is critical for correct invocation and goes far 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 opens with a specific verb and resource: 'Check whether an IOC has been revoked.' This clearly distinguishes it from siblings like 'lookup_ioc' (which likely retrieves IOC details) and 'revoke_ioc' (which performs revocation). The scope is 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 description explicitly states when to use this tool: 'Use this before acting on any cached threat intelligence to ensure the IOC has not been retracted since it was loaded.' This provides clear timing and purpose. It does not name alternatives or exclusions, but the context is strong enough to guide an agent.

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 burden of disclosing behavior. It states it returns all families and lists the included fields, but it does not explicitly state read-only status, permission requirements, potential response size, or any other behavioral nuances. The behavior is largely inferred from the verb 'Return'.

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, front-loaded with the main purpose, and includes a useful pointer to a sibling tool. There is no fluff or redundancy, every sentence contributes.

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 list tool with an output schema available, the description fully covers what the tool does, what the entries contain, and how to proceed to get IOCs. It is self-contained and 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 tool has zero parameters, so the baseline is 4. The description adds no parameter information because none exists, and the schema is trivially complete. No explanation is needed or provided.

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 returns all known malware families, the resource is specific, and it distinguishes itself from the sibling family_threats by explicitly referencing that tool for retrieving IOCs.

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 tells the user to use family_threats(family_name) for IOCs, providing a clear alternative and implying this tool is for browsing the full family list. This is direct guidance on when to use this tool versus the sibling.

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 the ordering (newest first), the meaning of since_hours (0 = no time filter, 'return all retained'), and the return structure (revocations, total, stats). It does not mention side effects, but as a list operation, this is expected to be read-only. The description adds useful behavioral context beyond the schema.

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

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

The description is well-structured with a one-line purpose followed by Args and Returns sections. Every sentence adds value: purpose, parameter semantics, and return field descriptions. No fluff or repetition, making it concise and front-loaded.

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 covers parameters and return values, and the simple nature of the tool (2 optional params, no output schema) means it is fairly complete. However, it does not specify what a 'revocation event dict' contains or how pagination works beyond the limit, but this is a minor gap for a list tool. It is adequate 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 has no descriptions (coverage 0%), so the description fully compensates. It explains limit as 'Maximum number of revocations to return (default 50)' and since_hours as 'Only return revocations newer than this many hours ago. 0 = no time filter (return all retained).' These are clear, meaningful semantics for both 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 states 'List recent IOC revocations, newest first' with a specific verb, resource, and ordering. This clearly distinguishes it from siblings like revoke_ioc (which creates a revocation) and is_ioc_revoked (which checks one), so the purpose is 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 description implies usage: it is a listing tool for viewing revocation history. However, it does not explicitly state when to use it versus alternatives (e.g., is_ioc_revoked for single checks), nor does it mention any exclusions or prerequisites. The context is implied rather than explicit, so it gets a minimal pass.

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 burden of behavioral disclosure. It clearly states what is returned (metadata) and what is not returned (the buffered IOCs), giving useful context about the tool's read-only nature and its output scope. This goes beyond a simple restatement of the 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?

Two concise sentences. The first states the primary action and scope, and the second clarifies output and use case. Every sentence earns its place with no wasted words.

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 a simple tool with no parameters and an output schema present, the description is complete. It covers what the tool does, what it returns, and a primary use case, which is sufficient for an agent to select and 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 description does not need to explain parameter meanings. Baseline for 0 params is 4, and the description appropriately avoids adding irrelevant 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 ('List') and clearly identifies the resource ('active stateful push subscriptions') and scope ('on this MCP server instance'). It also explicitly differentiates from siblings by stating it returns metadata, not the buffered IOCs themselves, which distinguishes it from tools like drain_subscription.

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 a clear context for when to use the tool: 'Useful for inspecting what agents are currently subscribed and what filters they have configured.' It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to understand its primary use case relative to the available 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?

No annotations are provided, so the description carries the full burden. It discloses that the record is returned only if found and lists the fields included. However, it does not describe not-found behavior, case sensitivity, or read-only guarantees, which could be important for a security-sensitive lookup.

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 one-line purpose, a one-line return summary, and a single parameter explanation. No unnecessary words, and the most important information is front-loaded.

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 adequately covers the core purpose, the parameter, and the return value, which is important since no output schema exists. Minor gaps include not specifying what happens when the IOC is not found and not distinguishing from similar search tools, but overall it is sufficiently complete for a simple lookup.

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 a type string and title, with 0% description coverage. The description compensates fully by explaining the parameter as 'The exact IOC value' and giving an example ('evil.example.com'), adding crucial meaning 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 function with a specific verb ('Look up') and resource ('threat signature by its exact IOC value'). The emphasis on 'exact' differentiates it from sibling tools like search_by_type, making its purpose distinct.

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 when to use the tool: when you have an exact IOC value. It provides clear context but does not explicitly name alternative tools or exclusion criteria, which is a minor gap given the large sibling set.

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 burden. It discloses the incremental fetch logic, the high-water mark, and the drain-backlog behavior. It could mention rate limits or side effects, but for a read-like fetch tool, it provides solid 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?

The description is compact and front-loaded, with the core purpose in the first sentence, followed by useful usage guidance and then parameter details. Every sentence contributes meaningful information without waste.

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 3 parameters and no output schema, the description covers the core workflow, including initial sync, pagination, and backlog draining. It does not detail the full response structure, but it names next_id and count, which are the essential returned fields. Slight gap on response schema is acceptable given the 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 schema has 0% description coverage, so the description fully compensates. The Args section explains each parameter's meaning and constraints, including last_id persistence, batch_size range, and min_severity scale, adding significant value beyond the raw 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 fetches new threat signatures since a high-water mark ID, using a specific verb and resource. It distinguishes itself from siblings by framing it as the recommended sync pattern with a one-call disconnect approach.

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 describes the intended usage pattern: call with last_id=0, persist next_id, pass it on next call, and drain backlog when count equals batch_size. It also mentions no persistent connection is required, implying when to prefer this over subscription-based tools, though it doesn't name alternatives explicitly.

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 full burden of behavioral disclosure. It clearly indicates a read-only operation by stating it 'Return[s] statistics' and 'verify[ies]' cache health, with no suggestion of side effects like cache modification. The term 'refresh status' is presented as a data field, not an action, avoiding ambiguity.

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 with no redundant content. The first sentence defines the return value, and the second provides the operative use case, making every sentence informative.

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 tool with no output schema, the description sufficiently enumerates the returned cache metrics (size, hit rate, latency, refresh status) and ties its usage to a specific sibling tool (check_prompt). This provides a complete operational picture without excessive 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 zero parameters, rendering parameter semantics trivially satisfied. The description avoids adding unnecessary parameter details, and the input schema already confirms the absence of parameters, so the 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 uses the specific verb 'Return' and names the resource 'PROMPT IOC cache statistics,' clearly stating its primary function. It distinguishes itself from siblings such as check_prompt and warm_prompt_cache by focusing on cache health metrics rather than detection or manipulation.

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 states when to use the tool: to verify the cache is warmed and healthy before relying on check_prompt() for real-time detection. This gives clear contextual guidance, though it does not mention alternatives or specific exclusion scenarios.

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. It implies a read-only operation but does not disclose ordering, time window, inclusivity (e.g., revoked or false positives), or other behavioral nuances that could affect interpretation.

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 front-loaded with the main purpose, followed by a clearly formatted Args list. There is no redundant text; every sentence provides useful information.

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

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

For a simple query tool with an output schema present, the description covers the core purpose and parameter semantics. Minor gaps remain around the exact recency timeframe and relationship to sibling tools, but overall it is largely complete for basic usage.

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 provides detailed parameter semantics that the input schema lacks, including ranges (1-200 for limit, 0-10 for min_severity), meanings, and default value interpretation. This fully compensates for the 0% schema description coverage.

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 a specific action ('Return') and resource ('most recently observed threat signatures'), which is understandable. However, it does not explicitly distinguish itself from similar siblings like get_new_threats or family_threats, leaving some ambiguity about unique scope.

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 provided on when to use this tool versus alternatives, nor any exclusions or recommended contexts. The description only states what the tool does, not when it should be chosen over 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 behavioral disclosure burden. It does well by not only stating the return data but also specifying the two inclusion criteria (initial ingestion and semantic drift), which are meaningful behavioral details. The verb 'Return' also implicitly signals a read-only operation. While it omits output format or pagination details, an output schema exists to cover that, so 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 two sentences long, with the primary purpose stated upfront. The second sentence adds valuable context about the two flag categories without redundant detail. Every word earns its place, and the structure is clean and 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?

For a zero-parameter retrieval tool with an output schema, the description is complete. It explains exactly what is returned and the two types of flags included. There is no missing critical information for an agent to invoke this tool correctly, and the output schema handles any return value details.

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 of 4 applies. The description adds no parameter-specific meaning because there are no parameters to explain. Schema coverage is 100% (empty object), so there is no gap for the description to fill.

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 the specific verb 'Return' and identifies the exact resource: all MCP tools flagged as suspicious or malicious. It further differentiates by listing the two flag source categories (initial high-risk fingerprint and semantic drift on update), making the tool's purpose unmistakable and distinct from sibling tools like get_new_threats 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 usage context is implied: use this tool when you need to list all flagged MCP tools. However, there is no explicit when-to-use vs. alternatives or any exclusion criteria. The description does not mention when not to use this tool or recommend an alternative, so it falls at the 'implied usage' level rather than providing clear contextual 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 burden. It clearly describes the returned data but does not explicitly state that this is a read-only, side-effect-free operation. However, the nature of 'statistics' strongly implies non-destructive behavior, and the description adds useful context about the specific metrics shown.

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, front-loaded with the main purpose and followed by concrete detail. No wasted words—every phrase contributes value.

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 stats tool with no output schema, the description is nearly complete—it list the key result fields. It could optionally mention the return format (e.g., JSON) or whether the stats are live or cached, but these are minor gaps for such a 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?

The tool has zero parameters, so the schema is trivially covered. The description adds meaning by detailing the outputs rather than parameters, which is appropriate here. With 0 params, the baseline is 4, and the description meets expectations without needing 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 clearly states the tool's purpose with a specific verb and resource: 'Return MCP registry monitoring statistics.' It then enumerates the exact metrics (tracked tool definitions, flagged count, drift detection rate), which distinguishes it from generic stats siblings like 'get_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 usage by virtue of its purpose—if you need registry monitoring statistics, this is the tool—but it provides no explicit when-to-use guidance or alternatives, such as 'use get_stats for broader stats' or 'not for per-tool details.' This falls into the 'implied usage' category.

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 key side effects: increments detection count and creates a real-time ThreatEvent visible to all agents. This is valuable context beyond what the schema provides. However, it does not mention authorization requirements or error behavior, so not a full 5.

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 concise paragraphs; every sentence serves a purpose. First paragraph states purpose and effects, second paragraph explains parameters in a list. No 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 3 params and no output schema. The description documents all params, side effects, and allowed actions. Minor gap: it doesn't specify return value or error cases, but overall it's sufficient for an agent to use 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 coverage is 0%, so description must explain all params. It does: signature_id references origin functions, action lists exactly five allowed values, context gives example content. This fully compensates for the schema's lack of descriptions.

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: reporting detection and action on a known threat signature. It specifies the verb 'report', the resource 'detection', and the additional effects (increment count, create ThreatEvent), which differentiates it from sibling tools like submit_ioc and lookup_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 provides clear context that this tool is for reporting detections after obtaining an IOC via submit_ioc or lookup_ioc. It implies the use case but does not explicitly mention alternatives or when not to use it, so a score of 4 is appropriate.

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 of disclosing side effects. It explicitly mentions the real-time push to all active subscriptions and explains that subscribers receive the revocation event on their next drain_subscription() call, which is a key behavioral trait beyond just 'revoking.'

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: a one-sentence purpose, a usage guideline, a detailed Args section, and a Returns summary. Every sentence adds value, and the structure is clean and front-loaded. It is appropriately sized for the tool's complexity.

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?

Despite having no output schema and no annotations, the description is self-contained. It explains the purpose, usage conditions, all parameter details, return values (event, pushed), and connected concepts like list_revocations and drain_subscription(). This is complete for a revocation 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 schema has 0% description coverage, so the description's Args section is essential. It adds detailed semantics for every parameter: value_hash format ('SHA256 of {ioc_type}:{value.lower()}'), reason's allowed values ('false_positive, expired, superseded, attribution_error, retracted'), and ioc_type's purpose ('optional, for subscriber filtering'). This exceeds 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 function: 'Revoke an IOC by its value hash, pushing the expiration event to all active subscriptions in real-time.' This is a specific verb+resource (revoke IOC) and distinguishes itself from sibling tools like submit_ioc, is_ioc_revoked, and list_revocations.

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

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

It gives explicit usage guidance: 'Call this when an IOC is determined to be a false positive, expired, or superseded.' This provides clear context for when to invoke the tool, though it does not explicitly mention when not to use it or name 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?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains the tool's role as a pre-execution defense, lists detection signals (e.g., download-and-execute chains, credential exfiltration), and details the return values including risk levels and should_block. This goes far beyond a simple 'scan' and gives the agent a thorough understanding of what the tool does and why.

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 an opening purpose, usage directive, detection signals, and Args/Returns sections. Every sentence earns its place, providing essential security context without redundancy. It is detailed but not bloated, and the critical instruction is front-loaded.

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 a complex tool with no output schema, so the description must explain both input and output. The Returns section comprehensively documents all fields (risk, risk_score, should_block, should_warn, kill_chain, signals, content_hash), and the detection signals give additional context. The description is fully self-contained for an agent to invoke and interpret 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 input schema provides only names, types, and requiredness with no descriptions, so the description must compensate. The Args section gives clear semantics: 'content: Full text content of the skill file' and 'source_url: URL where the skill was fetched from (for reporting).' This adds meaning the schema does not provide, making parameter usage clear.

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 begins with a specific verb and resource: 'Pre-execution content scan for skill/instruction files.' It clearly states the tool's role as a security scanner for malicious patterns, distinguishing it from sibling tools like validate_skill or check_prompt. The purpose is unambiguous and immediately understandable.

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?

Explicit usage direction is provided: 'Call this on any skill/instruction content fetched from the web before executing any of its steps.' It also states the conditional action: 'If should_block is True, refuse to proceed.' This gives the agent clear when-to-use guidance and a resulting behavior, which is especially important for a security-critical 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?

No annotations are provided, so the description must disclose behavior. It states the filtering behavior and parameter defaults (limit, min_severity), but does not describe pagination, ordering, or response format. For a read-only search tool, this is basic but adequate, though it could add more detail about result cap/paging.

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: two sentences followed by a neat parameter list. It is front-loaded with the core purpose and each line 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 output schema exists, the description doesn't need to cover return values. For a straightforward search tool, it covers purpose, parameters, and typical use cases, though it could explicitly differentiate from related tools like lookup_ioc to be 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?

Schema coverage is 0%, and the description fully compensates by documenting all three parameters. It lists the allowed ioc_type values, the limit range (1-1000) with default, and min_severity range with default, adding meaning the schema lacks.

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 verb+resource: 'Return threat signatures filtered by IOC type.' It distinguishes from sibling tools by focusing on type-based bulk retrieval (e.g., 'all known-bad IPs') rather than individual lookup or freshness checks.

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 clear context: it's useful for pulling all indicators of a specific type, such as known-bad IPs or malicious domains. It does not explicitly mention alternatives or when not to use it, so it stops short of explicit exclusion, but the context is sufficient.

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 behavioral disclosure burden. It explains the return format (one result per input in the same order), but does not mention partial failure handling, batch size limits, or authentication requirements. Solid but with clear 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?

Compact and well-structured; the lead sentence states the purpose, followed by use case, return behavior, and a concise parameter summary. Every sentence adds value.

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 batch tool with no annotations and a sparse schema, the description covers input structure, required/optional keys, and return ordering. It does not mention partial failure behavior or limits, but the existence of an output schema reduces the need for return-value 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 schema only declares an array of generic objects with no per-item properties. The description compensates by specifying required keys (ioc_type, value), listing optional fields (severity, confidence, context, tags, source, family_hint), and referencing submit_ioc's 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?

Clearly states 'Submit multiple IOCs in a single call' with a specific verb and resource. It distinguishes itself from the sibling tool submit_ioc by noting it is preferred over looping for bulk ingest.

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 recommends using this tool over looping submit_ioc for bulk ingest from honeypots, sandboxes, or feed processing, naming the alternative and giving concrete use cases.

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 does disclose useful behavioral traits: automatic classification, metadata compression, atomic deduplication, and instant visibility to subscribers. However, it omits the return value or success/failure behavior, and does not explicitly state any side effects like whether an existing IOC gets replaced or if duplicates are silently ignored (though dedup is implied).

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: a concise summary paragraph followed by a clearly formatted Args list. Every line serves a purpose, and the parameter documentation is easy to scan. It is slightly verbose but not wasteful, earning a 4.

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 covers all parameters and several behavioral aspects (classification, dedup, propagation). However, with no output schema, it fails to specify what the tool returns (e.g., an IOC ID, success message) or any error scenarios. For a mutation tool, this is a significant gap. It also doesn't mention prerequisites like authentication or rate limits.

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 description coverage is 0%, and the description fully compensates with detailed parameter semantics. It provides the full enum for ioc_type, severity with named enum values, confidence range, example formats for value, tags, and source, and explains the purpose of family_hint. This is exceptional added value beyond the raw 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 action with a specific verb and resource: 'Submit a threat indicator (IOC) to the shared intelligence network.' It also mentions unique behaviors (automatic classification, compression, atomic deduplication, instant propagation) that distinguish it from sibling tools like lookup_ioc or revoke_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 implies the tool is for submitting a single IOC, but it does not explicitly contrast with the sibling tool submit_batch or other alternatives. There is no 'when to use this vs. that' guidance. The context is clear for a submission operation but lacks exclusions or 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?

With no annotations, the description carries the full burden and does so thoroughly: stateful subscription, 1-hour inactivity expiration, independent copies for multiple subscribers, SSE mode requirement, and return fields (subscription_id, push_active, filters). This gives comprehensive behavioral expectations.

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-organized with clear sections (purpose, usage, args, returns) and every sentence adds meaningful information. While it is long, the length is justified by the tool's complexity, and it 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 the complexity of a stateful subscription with filters, expiration, and transport requirements, the description covers all critical aspects: lifecycle, filter behavior, operational prerequisite, and return values. No significant gaps remain.

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 fully. It explains each parameter's default, valid values for ioc_types, empty-list semantics for all composition filters, and the min_severity range. This is far beyond what the schema provides.

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 identifies the action ('Open') and the resource ('live threat push delivery'), and distinguishes this from siblings like drain_subscription and unsubscribe by explaining it creates the subscription. It is specific and 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?

It explicitly instructs to pass the returned subscription_id to drain_subscription() and notes zero polling, implying a contrast with polling-based alternatives. However, it does not explicitly name alternative tools such as get_new_threats or poll_since, so it falls short of full when-not-to-use 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, the description carries the full burden and does so well. It discloses the stateful nature, buffer freeing, memory release, auto-expiration policy, return statuses ('ok' vs 'not_found'), and the side effect of discarding unread signatures (drained count). This is comprehensive for a simple 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 and front-loaded with the main action. It includes only essential information: purpose, when to use, parameter explanation, and return values. Every sentence adds value 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 tool with one parameter and no output schema, the description is complete. It covers the action, usage context, return behavior, and even notes the auto-expiration policy. No gaps are apparent given 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 schema only provides the parameter name and type with no description (0% coverage). The description adds critical semantics: subscription_id is 'The ID returned by subscribe_threats()'. This fully compensates for the schema's lack of explanation.

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 the specific verb 'Cancel' with the resource 'stateful subscription' and clearly states the action of freeing its buffer. It distinguishes itself 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?

The description explicitly says when to call: when you no longer need the subscription to release memory. It also informs that subscriptions auto-expire after 1 hour, implying the tool may be unnecessary in that case. However, it does not explicitly mention alternatives like drain_subscription or when not to use the tool, so it falls short of 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 full burden. It discloses synchronous behavior, the allow/warn/block decision, hash-based matching, and fallback logic via manifest_url. It doesn't mention auth or rate limits, but the read-only validation nature is clear from 'check' and the decision-oriented return.

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

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

The description is front-loaded with the essential purpose, then uses a tight Args/Returns structure. Every line adds necessary information — param semantics and return fields — 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?

Given no output schema, the description fully documents the return object (risk, action, confidence, signature_id, family_name, reason) and explains the fallback behavior. It also covers all three parameters and the enforcement context, making it self-sufficient 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?

Schema coverage is 0% (only titles/defaults), so the description must compensate — and it does. Each parameter gets meaningful context: skill_hash is 'SHA256 of the skill manifest (preferred identifier)', skill_name is 'for logging', manifest_url is 'fallback if hash unknown'. This goes well beyond the bare 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 'Synchronous SKILL IOC lookup' and explicitly states 'call this before loading or invoking any MCP tool/skill' — a specific verb, resource, and timing. It distinguishes itself from siblings like lookup_ioc and scan_skill_content by framing itself as a pre-invocation enforcement hook.

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 when-to-use guidance: 'call this before loading or invoking any MCP tool/skill' and labels itself 'pre-invocation enforcement hook.' It doesn't mention alternatives or when-not-to-use, but the context is explicit enough for an agent to select this over passive lookup 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 well by disclosing the voting mechanism and the threshold for setting is_likely_fp. It also clarifies that this is a signal to review, not an immediate block. This goes beyond the schema by explaining the collective behavior and outcome.

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-line purpose, a brief explanation of the threshold, and a clean Args list. Every sentence adds useful information with no redundancy, making it easy to parse and act on.

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 relatively simple voting tool, the description covers the core action, the threshold behavior, and parameter semantics. It does not mention the return value or whether votes can be repeated/idempotency, which would be useful, but the existing information is sufficient for most usage. The lack of output schema and annotations raises the expectation slightly, but the description is still fairly 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 Args section explicitly explains both parameters: signature_id as the ID of the ThreatSignature and reason as an optional explanation. Since the schema provides no descriptions (0% coverage), this explanation is essential and fully compensates, giving the agent clear guidance on what each parameter means.

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 action: 'Flag a threat signature as a likely false positive.' It clearly identifies the resource (threat signature) and the verb (flag/vote), and further distinguishes the tool by explaining the 20% threshold mechanism. This differentiates it from sibling tools like revoke_ioc or report_detection.

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 clear context for when to use the tool: when you believe a signature is a false positive, and it explains the consequence (flag set after 20% votes). It does not explicitly name alternatives or 'when-not-to-use' situations, but the context is sufficient for an agent to recognize the appropriate scenario.

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 that the tool loads all IOCs into an in-memory hash set, auto-refreshes in the background, and makes subsequent check_prompt() calls require no network access. The return fields are described, adding useful behavioral context. It does not mention memory footprint or consequences of not calling, but the key behaviors are covered.

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 first sentence stating the action, followed by usage guidance and a Returns section. Every sentence earns its place, and the formatting is 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?

Given the lack of parameters and output schema, the description covers the essential aspects: what the tool does, when to call, auto-refresh behavior, and return values. It could be slightly more explicit about prerequisites or memory effects, but it is sufficiently complete for an agent to decide whether and how 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. No parameter descriptions are needed, and the description appropriately focuses on behavior and return values.

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 function: 'Load all PROMPT IOCs from SpacetimeDB into the in-memory hash set.' The verb 'load' and resource 'PROMPT IOCs' are specific, and the scope differentiates it from siblings like check_prompt 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 gives explicit timing guidance: 'Call once at startup (or after a major feed update).' It also mentions the auto-refresh every 5 minutes, providing clear context. However, it does not explicitly discuss alternatives or exclusions, though the reference to check_prompt() implies the normal query path.

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