Hackertarget

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavior beyond that: the default model (Llama-3.3-70b), the free tier, the cost implication of passing _apiKey ("you pay Anthropic directly"), and the external call to api.anthropic.com. This enriches the annotations without contradicting them.

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 main action is front-loaded in the first sentence, and each subsequent sentence earns its place: cost/model behavior, return format, and use cases. It is slightly dense — the cost point and return format could be tightened — but there is no fluff or redundancy beyond a minor BYO-key/pay overlap.

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 present, the description correctly fills the gap by specifying the return shape (per-model score, confidence, signals, raw_response + combined view). It also covers cost, defaults, and use cases. Minor gaps remain: the meaning/orientation of the 0-100 score (higher = better visibility?) and failure behavior when anthropic is requested without _apiKey are not explained.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters with examples and format hints. The description adds only marginal enrichment — the concrete default model identity (Llama-3.3-70b) and the free-vs-paid cost distinction for models/_apiKey. This is a solid baseline with slight bonus, but the schema carries the heavy lifting.

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 specific verbs and resources: "Probe one or more LLMs... and score visibility (0-100) per model." It names the subject (business/brand/product/topic), the action (probe + score), and the output shape, making it clearly distinguishable from Q&A siblings like ask_pipeworx and research tools like deep_research.

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 final sentence gives concrete use cases ("AI-marketing audits, pre-launch brand checks, competitive monitoring"), and the second sentence provides operational guidance on model selection (default free model vs. BYO Anthropic key). However, it does not name alternative tools or state when not to use it, e.g., versus the sibling scan_competitor_ai_presence.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds valuable behavioral context: routes to the right sub-tool, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, makes one fast call, and handles breaking news via live news feeds. No contradiction with annotations.

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

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

The description is dense but well-structured: it front-loads the decisive directive 'PREFER OVER WEB SEARCH', then moves through scope, trigger phrases, examples, and escalation paths. Every sentence earns its place, and formatting elements like 'START HERE' and 'Step up only when needed' aid quick scanning.

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 explains the return format (structured answer with citation URIs). It also covers when to escalate to alternatives, breaking-news behavior, tier availability, and the kinds of data domains covered, fully equipping an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema itself fully documents the question parameter and its aliases (q, text, input, query, prompt). The description's examples illustrate good natural-language inputs but do not add parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb (routes) and resource (Pipeworx's 6,020 tools across 1,567 sources), and explains that it fills arguments and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart immediately.

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 'PREFER OVER WEB SEARCH', provides trigger phrases ('what is', 'look up', 'find', etc.), gives concrete examples, and names alternative tools with conditions: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. It also positions itself as the 'START HERE' default entry point.

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?

Discloses that it's an experimental variant with candidate improvements enabled live only when under test, and that no candidate is active since 2026-07-26 so it currently performs identically to the stable router. Also clarifies it is a full working router with no fallback, adding context beyond the annotations' read-only/idempotent hints.

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

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

Every sentence adds distinct value: identity/scope, current state, usage instruction, and fallback disclaimer. The beta context is front-loaded before usage guidance.

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 router with no output schema, it references ask_pipeworx's response shape and covers experimental status, current parity, and usage intent. No missing information prevents 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 covers 100% of parameters and documents all aliases (q, text, input, query, prompt) as synonyms for question, so the description adds no new parameter semantics beyond saying 'same arguments.' Baseline 3 applies.

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

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

Identifies itself as a beta version of ask_pipeworx, an identical universal router with the same 6,020 tools, arguments, and response shape. Explicitly contrasts with the stable ask_pipeworx by calling itself the experimental edge, which distinguishes it from sibling ask_pipeworx_grounded and ask_pipeworx.

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

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

Gives explicit when-to-use instruction: 'Use it exactly like ask_pipeworx when you want the newest routing.' States that results are compared against the stable router and that it currently matches ask_pipeworx exactly, telling the agent when it's safe to use the beta vs the stable 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?

Annotations already cover safety hints (readOnly, idempotent), but the description adds crucial behavioral details: the extraction-only-from-tool-result guarantee, explicit refusal reasons, and the extra LLM call cost. It also discloses the internal process of picking and filling arguments, which annotations do not mention.

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 core value proposition, then systematically covers routing, extraction, output structure, usage guidance, and cost tradeoff. Every sentence earns its place; there is no filler or repetition.

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

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

With no output schema, the description fully documents the return shape and all refusal reasons, and explains the cost difference from ask_pipeworx. It gives an agent all needed context for correct invocation and interpretation, despite the tool's complexity.

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

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

Schema coverage is 100%, with each parameter already described as an alias for 'question.' The description adds no new parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' a specific verb-resource pair that immediately distinguishes it from the sibling ask_pipeworx. It then details the routing and extraction process, making the tool's purpose unmistakable.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool, providing clear routing criteria.

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

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

Annotations already declare this as read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. However, the description adds no behavioral context about data sources, rate limits, result structure, or any quirks. It merely repeats the tool name, adding little value beyond the annotations.

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

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

The description is extremely short, but it is under-specified rather than concise. It contains no usable information beyond restating the tool name and source. It does not front-load any meaningful guidance, so the brevity is not a virtue.

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 is a simple lookup with one parameter and annotations covering safety, one might expect a minimal description to suffice. However, the description is so sparse that it fails to explain the tool's purpose, parameter semantics, or return value. It is not complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema defines a single 'target' string parameter with zero description. The description does not compensate for this 0% schema coverage; it never explains what 'target' refers to (e.g., IP, domain, ASN, or something else). This leaves the agent unable to infer correct parameter 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 'HackerTarget as_lookup lookup' is essentially a restatement of the tool name and source. It does not specify what kind of lookup is performed (e.g., autonomous system lookup), what the target means, or what information is returned. It fails to distinguish itself from sibling lookup tools like dns_lookup or reverse_ip.

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 usage guidance is provided. The description does not explain when to use this tool versus alternative lookup/OSINT tools in the sibling list, nor does it mention any prerequisites or contexts where this lookup 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?

Annotations cover only the safety profile (readOnly/openWorld/idempotent/non-destructive), and the description adds far beyond that: BLOCKING short-circuit statuses (low_confidence_match, market_closed_or_inactive, market_expired_or_resolved), the resolver contract with match confidence scores, GDELT 429 fallback fields, illiquid_wide_spread flagging, and cancellation-rule settlement parsing. These are exactly the operational traits an agent needs to avoid misusing results (e.g. sizing on phantom matches).

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

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

Purpose is front-loaded, but the body is an unusually dense wall of ALL-CAPS headers and enumerated classifier/fan-out/status lists. Much of this is useful given the absent output schema, yet the density and length exceed what most agents will parse, so structure is adequate but not economical.

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

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

With no output schema, the description carries the full return-shape burden and does so: result.market fields, result.analysis fields (model_probability/edge_pp/kelly_fraction_half), result.evidence keying, resolver contract fields, parent_event partition fields, and news fallback metadata are all documented. An agent can interpret responses without guessing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains WHY to prefer an undated slug (dated slugs stop resolving once settled because Polymarket de-indexes resolved markets) and ties fuzzy matches to the suggestions[]/market_match_alternatives[] re-query hints. The depth and include_raw semantics largely restate the schema, so it is not a full 5.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and enumerates the full pipeline (resolve → classify → fan out → evidence packet + model comparison). Sibling Polymarket tools (edges, arbitrage, fill_risk, kalshi_spread) are implicitly distinguished by the 'should I bet on X / what does the data say / is there edge' trigger framing, which reads as research rather than scanning or spread-monitoring.

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?

Trigger phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') give clear usage context, and the safety section explains when the tool effectively won't produce analyzable output. However, it never names an alternative sibling or states when NOT to use this tool (e.g. bulk edge-scanning belongs to polymarket_edges/arbitrage), so routing vs. alternatives is left to inference.

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

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

Beyond the read-only/idempotent annotations, the description reveals important runtime behavior: it executes as one parallel call, pulls specific financial fields from SEC EDGAR/XBRL or FAERS data, handles off-calendar fiscal years, sorts results by the primary metric, and returns paired data with citation URIs. This is far more than the annotations alone provide.

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

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

The description is dense but every sentence earns its place: trigger phrases, selection guidance, type-specific data sources, output ordering, and citations. Important guidance is front-loaded with the natural-language triggers and the 'ALWAYS PREFER' instruction.

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 lacking an output schema, the description tells the agent what data will come back, how results are ordered, what citations are included, and why this tool beats sequential lookups. An agent has enough information to select and invoke it correctly without needing further clarification.

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?

Although the schema already covers both parameters at 100%, the description adds meaningful semantics: it explains what each type value retrieves, gives concrete ticker and drug examples, and clarifies that values must be 2–5 entities. This goes well beyond the schema's minimal 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 opens with concrete user phrasings ('Compare X and Y' / 'X vs Y' / 'rank these companies') and then states the core operation: side-by-side comparison of 2–5 companies or drugs in one parallel call. It also distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear selection rule. It gives trigger examples, the entity types, the count range, and the value proposition ('Replaces 8–15 sequential lookups'), so an agent knows exactly 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?

Adds rich behavior beyond annotations: account/paid-plan requirements, parallel routing, gap[] reporting with never-invented guarantee, citation fetchability contract, hop semantics, contradiction scanning, excerpting, and timing. No claim conflicts with the readOnly/openWorld/idempotent hints.

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

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

The description is long but every section earns its place for a complex tool, and the most decision-relevant facts (account requirement, alternative tool) are front-loaded. Slightly dense, but not padded.

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 fully covers return shape (findings packet fields, gaps, contradictions, hop/citation), failure behavior, latency, auth, and when to pick siblings. An agent has everything needed to call 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?

Input schema already documents both params with 100% coverage, so baseline 3 applies. The description adds minor value by tying depth:'thorough' to paid access and giving expected time ranges, but it does not materially deepen parameter semantics.

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

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

States a specific verb and resource: grounded multi-source research across 1,567 structured data sources via parallel facet decomposition. It contrasts itself with single-lookup ask_pipeworx and explicitly says it is NOT open-web search, making its identity 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?

Gives explicit when-to-use guidance ('best for broad/multi-part questions over structured data'), and names ask_pipeworx as the alternative for single lookups, breaking/current news, and unsigned-in users. This is actionable routing with no reliance on inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds substantial value by disclosing the exact return shape: top-N relevant tools with names, descriptions, full input schemas and curated examples, and that results are ready to call without a second schema lookup. This is especially useful because no output schema is provided.

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 core purpose, followed by use cases, return value, and a clear first-step instruction. Each sentence earns its place, and the domain list is dense but directly relevant.

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 discovery tool with straightforward parameters, high schema coverage, and no output schema, the description fully compensates: it explains what the tool does, when to use it, and exactly what the response contains. Nothing materially needed by an agent is missing.

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

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

Schema coverage is 100%, and the schema already documents query, all aliases, and limit defaults/max. The description only restates that the input is a natural-language description of a data/task, adding no parameter-level 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 first sentence names a specific action and resource: 'Find tools by describing the data or task.' It also lists concrete domains and frames the tool as a discovery/meta tool, which distinguishes it from the many operational sibling tools and clarifies it is not itself a domain-specific search.

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 use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST when many tools are available. It does not name specific alternative tools or give explicit exclusions, though 'not just one answer' hints at when a direct tool is more 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) indicate a safe read-only operation, but the description itself adds no behavioral context. It does not explain how the lookup behaves, what data is returned, or any limitations.

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 one short sentence, but it is under-specified rather than concise. It omits essential meaning and does not communicate the tool's purpose or usage effectively.

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 a single parameter and no output schema, this description is far too minimal. It gives the agent no understanding of what input to provide or what output to expect, making correct invocation nearly impossible.

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 defines a single 'target' string with no description, and the tool description provides zero explanation of what 'target' should be (e.g., a domain name, IP address, or hostname). With 0% schema coverage, the description fails to compensate.

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 'HackerTarget dns_host_search lookup' essentially restates the tool name with a generic verb. It fails to specify what is actually searched or what the tool returns, and it does not differentiate it from sibling DNS tools like dns_lookup or reverse_dns.

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 about when to use this tool versus alternative lookup tools. There is no mention of use cases, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. However, the description adds no behavioral context—no rate limits, input format expectations, or return structure. It only names a third-party service, which is not 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 extremely short, but it is under-specification rather than conciseness. It says nothing beyond repeating the tool name, so the brevity does not serve the agent's needs.

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 tool with no output schema, the description should at least state the tool's purpose and expected input. This description provides virtually no context, making it inadequate for the agent to correctly select or invoke the tool, especially amid many DNS-related siblings.

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

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

The only parameter 'target' has no schema description, and the tool description provides zero information about what format or values it expects. With schema description coverage at 0%, the description completely fails to compensate, leaving the agent unable to know if 'target' should be a domain, IP, or something else.

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 'HackerTarget dns_lookup lookup' is essentially a tautology, repeating the tool name without specifying what kind of DNS lookup is performed (e.g., forward, reverse, record types). It does not distinguish from sibling tools like reverse_dns or dns_host_search.

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?

There is no guidance on when to use this tool versus alternatives. No mention of target types (domain, IP), expected use cases, or exclusions. The agent is left without any context to choose between this and similar DNS 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?

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds genuinely useful behavioral context: one parallel call, USPTO soft-fail behavior, FDA small-molecule expected-empty case, resolved:false + notes for private companies, and sources_used/sources_failed semantics. This goes well beyond what annotations provide, though it doesn't document rate limits or latency.

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

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

The description is long but information-dense; the trigger examples are front-loaded, then the fan-out list, then return semantics. It earns its length by covering many data-source edge cases and expected failures. It could be tightened with bullets, but the content is purposeful and not padded.

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 broad fan-out and no output schema, the description covers inputs, resolution behavior, per-source quirks, and failure semantics well. The main gaps are missing names or numbers of sibling tools that would further disambiguate it from deep_research or compare_entities, and no explicit mention of typical latency or upper bound on sources.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully, including the interchangeability of type values and the accepted value shapes. The description reinforces the same semantics and adds the resolved_from/resolved_to nuance for name-based values, but its baseline is the schema doing the heavy lifting.

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 concrete trigger phrases and a clear verb-object pair ('full cross-source profile of a US public company'). It names the resource and the fan-out sources, and explicitly contrasts with chaining single-pack lookups, which differentiates it from siblings like deep_research, compare_entities, and resolve_entity.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', gives accepted input shapes, and explains the empty-section semantics and private-company fallback. This gives clear when-to-use and when-not-to-fail 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?

The description adds no behavioral context beyond the annotations. While annotations (readOnlyHint, idempotentHint, etc.) already indicate a safe read operation, the description does not mention input formats, rate limits, or any operational details that would help the agent anticipate 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 extremely short, but it is under-specified rather than concise. A single phrase that merely echoes the tool name does not earn high marks for structure; it lacks substantive content while still occupying space.

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 sparse schema and absence of an output schema, the description needed to explain the tool's purpose and parameters. It fails to do so, making the tool effectively unusable without external context about HackerTarget or shared DNS. The description is incomplete for even a simple one-parameter 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 input schema has one parameter 'target' with no description, and the schema description coverage is 0%. The description does not explain what 'target' represents (e.g., a domain, IP, or hostname) or how it should be formatted, leaving the agent without essential parameter semantics.

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

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

The description 'HackerTarget find_shared_dns lookup' mostly restates the tool name, adding only the vendor 'HackerTarget' and the generic verb 'lookup'. It does not specify what 'shared DNS' means or what action is performed, so it fails to clearly distinguish from sibling tools like dns_lookup or dns_host_search.

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 usage guidance is provided. There is no mention of when to use this tool versus alternatives such as dns_lookup, reverse_dns, or as_lookup, nor any indication of prerequisites or appropriate contexts.

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

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

The explicit 'Delete' verb aligns with the annotations destructiveHint=true and readOnlyHint=false, and key-based deletion is consistent with idempotentHint=true. No contradiction. The description adds context beyond the flags by scoping the target to 'previously stored memory by key' and by noting the sensitive-data use case, though it does not describe edge-case behavior like deleting a missing key.

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

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

Three short sentences with the core action front-loaded, followed by usage triggers and sibling pairing. Every sentence earns its place; there is no filler or redundant restatement of the schema.

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

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

For a one-parameter delete action, the description covers purpose, usage conditions, sibling context, and destructive nature; annotations cover idempotency and mutation, and the schema covers the parameter with an example. Nothing material an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 100% and the schema already documents key as 'Memory key to delete' with an example. The description merely restates the mechanism as 'by key,' adding no format, lifecycle, or edge-case semantics beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb ('Delete') with a specific resource ('previously stored memory') and the mechanism ('by key'). The description also names the paired sibling tools remember and recall, making the tool's role in the memory family 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?

Gives three explicit trigger conditions: stale context, task complete, and clearing sensitive data previously saved by the agent. Names the related tools remember and recall as its pair, though it stops short of an explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety/purity of the operation is established. The description adds valuable behavioral context: it fetches the page, extracts specific elements, and emits a single text blob ready for site-root deployment. It does not disclose edge cases (e.g., inaccessible URLs), but the annotation coverage lowers the burden.

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 tight sentences: purpose, process/output, and use cases. Every sentence earns its place, the core action is front-loaded, and the use-case list communicates practical value without drifting into irrelevant detail.

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 simple tool with only two parameters, full schema coverage, and annotations covering safety and idempotence. The description explicitly states the output format and where to place the result, compensating for the absence of an output schema. An agent has everything needed to invoke it correctly for typical use cases.

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

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

Schema description coverage is 100%: url and max_links are both explained, including max_links' default (25) and maximum (50). The description adds no meaning beyond 'any URL' and does not mention max_links at all, so it stays at the baseline of 3 where the schema carries the parameter documentation.

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: 'Generate a production-ready llms.txt file for any URL.' It clearly details the process (fetches page, extracts title/description/key links) and the exact output (single text blob in standard llms.txt markdown), making it easy to distinguish from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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 'Useful for:' section provides concrete scenarios for when to invoke this tool: indexing a client's site, drafting for one's own project, or auditing how an AI crawler sees a competitor. It does not explicitly name alternative tools or describe when not to use it, but the context is sufficiently 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?

Annotations already communicate read-only, open-world, and idempotent behavior. The description adds no extra context such as response format, data source, or any limitations. Since there is no output schema, the description should disclose what a lookup returns (e.g., geolocation fields), but it does not.

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 very concise at only four words, which is structurally simple and front-loaded. However, it sacrifices necessary information for brevity, making it less effective than a slightly longer description could be.

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 a single parameter and no output schema, the description carries the full burden of explaining what the tool does. It only states 'HackerTarget geoip lookup,' which is insufficient for an agent to know how to set the target or what to expect in response. Given the tool's simplicity, a more complete description is expected.

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 defines a single required string 'target' with 0% description coverage. The phrase 'geoip lookup' implies the target is an IP address or hostname, but this is not explicitly stated. The description fails to adequately compensate for the lack of parameter documentation.

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 'HackerTarget geoip lookup' clearly identifies the tool as a GeoIP lookup service powered by HackerTarget. It distinguishes itself from siblings like dns_lookup and whois by focusing on geographic IP data. However, it lacks details on input format and output, preventing a top score.

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 offers no guidance on when to use this tool versus alternatives. It does not explain whether it is for IP addresses, domains, or how it complements other recon tools. Given the large sibling set, explicit context is essential but missing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, which covers safety. The description adds no additional behavioral context such as external API dependencies, rate limits, or output format, providing no value beyond the annotations.

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

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

The description is extremely brief, but this is under-specification rather than conciseness. It is not a full sentence and lacks any informative structure, offering no useful content beyond the tool name.

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?

Even for a simple tool, the description should at least clarify what target refers to and what the output will be. The lack of an output schema increases this need, but the description provides neither, making it incomplete for an agent to use correctly.

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

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

The only parameter 'target' is a required string, but the description does not explain what it means (e.g., a domain, URL, or IP). With schema description coverage at 0%, the description fails to compensate, leaving the parameter's semantics completely unexplained.

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 'HackerTarget http_headers lookup' essentially restates the tool name with the verb 'lookup' and the provider, but does not explain what http_headers does (e.g., retrieving HTTP headers for a given target). It does not distinguish from sibling tools beyond the name, making it a near-tautology.

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?

There is no guidance about when to use this tool versus alternatives like dns_lookup or whois. The description provides no context, prerequisites, or examples of appropriate use.

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

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

The description goes far beyond the annotations by disclosing non-obvious behavioral traits: markets settle on Weather Company, not NWS; station is derived from settlement clause; forecast_prob uses an assumed normal distribution; edge_pp is gross; and it exposes a concrete measured result showing the market beat the forecast. These are exactly the kind of caveats an agent needs to interpret results correctly, and they are not visible in the read-only/open-world annotations.

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

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

The description is long but tightly packed with critical trading caveats. It is front-loaded with purpose and modes, then structured warnings (1-4), then a measured result, followed by edge-case handling. While not concise, the density is justified given the financial stakes and the need to prevent misuse; it could be slightly more scannable with headers, but overall each sentence carries weight.

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 specify return values, and it does: LIVE mode returns the strike ladder with market_prob, forecast_prob, edge_pp, and the settlement clause; BACKTEST returns brier_market vs brier_forecast, settlement-vs-forecast basis, and a plain-English verdict. It also covers international and precipitation fallbacks, and the warning section covers all major edge cases. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning to each parameter: 'city' includes a default and fallback behavior (unmapped cities return known_cities[]), 'date' explains open/close timing, 'market_type' clarifies precipitation returns no forecast, 'backtest_days' explains the scoring methodology and max, and 'series_ticker' overrides city. This is a textbook example of enriching schema with operational context.

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: 'Prices Kalshi daily high-temperature markets against the NWS forecast...' and explicitly defines two modes (LIVE and BACKTEST) with distinct outputs. It differentiates itself from sibling tools by focusing on a niche weather-edge analysis, and the many specific details (station codes, edge_pp, brier scores) leave no doubt about its purpose.

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

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

The description provides explicit when-to-use guidance: 'LIVE (default)' vs 'BACKTEST (`backtest_days: N`)', and tells the user to run backtest before believing any edge. It also covers exclusions: international series return forecast_unavailable, precipitation is not priced, and it warns about using city-centre forecasts when stations are derived from settlement clauses. This is model-guidance beyond what any sibling alternative offers.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail by scoping to the caller's active subscriptions and enumerating the returned fields, which goes beyond what annotations provide.

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

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

Two sentences carry all the essential information: what the tool lists, what it returns, and when to use it. The primary action is front-loaded and there is no redundant wording.

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

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

For a simple read-only list tool with one optional documented parameter and no output schema, the description is complete: it names the resource scope, the returned fields, and the use cases. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the single optional include_inactive parameter is already fully documented. The description does not add further parameter context, which matches the baseline of 3 for high schema 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 names a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact return fields, making the operation concrete and clearly distinct from sibling tools like subscribe 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 explicitly says when to use this tool: 'review what you're monitoring before adding more' and 'find an id to cancel.' It gives clear context, though it does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the annotations—it does not mention external service dependencies, rate limits, or any side effects. It is consistent with annotations but adds no value.

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 short but under-specified rather than concise. A single phrase like 'HackerTarget mtr lookup' does not earn its place because it provides no meaningful information. This is closer to a placeholder than a well-structured description.

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 a single parameter, no output schema, and minimal annotations, the description still fails to provide essential context such as what mtr does, what kind of output to expect, or how it differs from the sibling 'traceroute' tool. It is minimally viable but leaves major gaps for an agent trying to decide when to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented 'target' parameter. The description only says 'HackerTarget mtr lookup' and fails to explain what the 'target' should be (e.g., IP address, hostname, domain). This is completely inadequate for an agent to understand how to fill the 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 'HackerTarget mtr lookup.' is essentially a tautology, restating the tool name 'mtr' and adding 'lookup' without explaining what mtr does. It does not distinguish this tool from siblings like 'traceroute' or 'dns_lookup'. The verb 'lookup' is present but the resource is unclear.

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 no guidance on when to use this tool versus alternatives such as 'traceroute' or 'ping'. There is no mention of context, prerequisites, or exclusions. The agent is left without any information to select this tool correctly.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds no behavioral context beyond stating the external source 'HackerTarget'. It does not explain what the tool does operationally (e.g., sends ICMP packets, checks host reachability, returns latency metrics) or any limitations. There is no contradiction with annotations, but the description contributes no meaningful 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 extremely short and front-loaded, but it is under-specified rather than concise. It consists of only three words, which is not enough to convey meaning. This is similar to the calibration example where under-specification receives a score of 2, not 5.

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 single parameter with no schema description, no output schema, and no sibling differentiation, the description is completely inadequate. It does not explain what the tool does, what input to provide, or what output to expect. Even for a simple tool, this is not enough information 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?

Schema description coverage is 0% and the only parameter 'target' is undefined in both the schema and the description. The description does not clarify whether 'target' is a hostname, IP address, or URL, nor does it explain the expected format or possible values. The description completely fails to compensate for the lack of schema documentation.

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 'HackerTarget nping lookup.' is essentially a tautology: it restates the tool name 'nping' and adds the generic verb 'lookup' without specifying what nping does, what resource it targets, or what kind of lookup (e.g., host availability, latency, packet loss). It does not distinguish this tool from network diagnostic siblings like mtr, traceroute, or dns_lookup.

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?

There is no guidance on when to use this tool versus alternatives. The description provides no context about typical use cases, prerequisites, or exclusions. Sibling tools such as mtr and traceroute exist, but the description gives no basis for choosing nping over them.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint safely, so the safety bar is lowered. However, the description adds no behavioral context beyond what annotations provide—no mention of return format, data source specifics, or API limitations. It adds zero value on top of the annotations.

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

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

The description is extremely short, but this is under-specification rather than effective conciseness. It consists of a single phrase that repeats the tool name without earning its place or conveying operational details.

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 a single param, no output schema, and a one-line description, the tool is severely under-documented. The agent cannot infer what input format to use or what results to expect. It is completely inadequate for correct invocation.

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

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

The only parameter 'target' is a required string with no description in the schema (coverage 0%). The tool description also fails to explain what 'target' means (e.g., domain, IP, URL). The agent has no information to construct a valid input.

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 'HackerTarget page_links lookup' essentially restates the tool name with the generic verb 'lookup'. It does not explain what page_links returns or how it differs from sibling tools like dns_lookup or reverse_dns. This is closer to a tautology than a clear statement of purpose.

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?

There is no guidance on when to use this tool or when to prefer an alternative. The description provides no context about typical use cases, prerequisites, or exclusions. The agent is left without any decision-making support.

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

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

Annotations are all false, so the description carries the burden—and it delivers. It discloses the anonymous claim_token flow, the behavior of passing the token later to read resolution status, rate limiting to 5 per identifier per day, freedom from quota, and the digest/roadmap impact. No contradictions with annotations.

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

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

The description is a single dense paragraph, but every sentence earns its place: scope, exclusions, token workflow, rate limit, and content guidance are all non-redundant. Slight restructuring into bullets or shorter paragraphs would improve scannability, but it is already front-loaded and free of 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?

For a complex feedback tool with nested objects, enum types, and no output schema, the description is remarkably complete. It explains what the response token means, how to follow up, what to include in the message, what not to include, rate limits, and scope. An agent has everything needed to invoke it correctly and to route unrelated feedback elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining how to frame the message (in terms of Pipeworx tools/packs, not end-user prompts) and how claim_token is used round-trip. It does not relist parameter names, but it enriches the practical meaning of 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 precise verb and resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly differentiates this from the sibling ask_* tools by specifying this is a feedback channel for Pipeworx itself, not a data-querying tool.

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

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

It explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to use it (issues with tools from other MCP servers, which should be filed with that server). This is the strongest possible usage guidance: concrete conditions, explicit exclusions, and a clear alternative action.

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

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

The annotations already mark this as readOnly, openWorld, idempotent, and non-destructive, and the description adds meaningful context beyond that: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This gives the agent a strong behavioral model of what it is querying.

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, front-loading the core purpose and then using a numbered list for use cases and a short final sentence for technical caveats. It contains minor redundancy around 'hot/current' language, but every sentence earns its place and the structure aids skimmability.

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 only one optional parameter, a fully descriptive schema, and strong annotations, the description covers what an agent needs to invoke the tool correctly: what it returns, the available windows, the caching behavior, and the privacy/aggregation properties. Since there is no output schema, the description's mention of 'top tools, top packs, and total call volume' provides sufficient return-value 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 input schema already provides 100% coverage for the single 'window' parameter, including the enum values, the default, and guidance on short vs long windows. The tool description only restates the window options and does not add unique parameter semantics beyond what the schema already covers, so the baseline of 3 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 opens with a specific, question-shaped statement — 'What other AI agents are calling on Pipeworx right now' — then names the concrete outputs: top tools, top packs, and total call volume. This clearly positions it as a meta/trending tool, distinct from related siblings like discover_tools, without needing to open the schema.

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

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

The description gives three explicit, practical use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with broader agent demand. It does not state when not to use this tool or explicitly name an alternative, so it falls just short of the top bar, but the usage context 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?

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes far beyond these by disclosing detailed fee modeling (taker fee rates, gas costs, fee_basis sources), the behavior when fees flip net_positive to false ('that is the correction, not a regression'), fill-check logic that can recommend not trading, and the partition filter that returns null under placeholder-heavy partitions. It also notes the tool does not double-count spread cost. This is exceptional transparency that anticipates potential misinterpretations.

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?

Although the description is long, every section earns its place: it is organized into clearly labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FEES, FILL CHECK) and front-loads the core purpose and invocation modes. There is no filler—each sentence adds a constraint, an example, or a caveat that an agent needs to invoke and interpret the tool correctly. Given the tool's inherent complexity, the density and structure are appropriate rather than verbose.

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 two optional parameters, no output schema, and high nominal complexity. The description compensates fully: it details the response shape (opportunities[] with fields, partition_check fields, fees components), explains edge calculations (gross, net, fee basis), covers edge cases (fill check, thin legs, placeholder filters), and references a companion tool for deeper analysis. An agent has everything needed to call it correctly and interpret results, even without an output schema.

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

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

While the schema descriptions for event and topic are already helpful (100% coverage), the tool description adds significant operational meaning: concrete example slugs ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), what the tool does with each value (walks child markets, runs partition checks, cross-event flattening), and the semantic/anchor filters (Jaccard similarity) that govern pairing. It even explains the difference between event and topic in terms of scope and output. This goes well beyond the schema's field-level comments.

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

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

The description opens with a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the mechanism from sibling tools (e.g., polymarket_edges likely focuses on edge detection, not arbitrage) and enumerates three operational modes (trending_scan, event, topic) that map to distinct use cases. No ambiguity about what the tool does.

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

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

The description explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. It even recommends event for specific markets and refers to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' It also explains the comparative advantage of cross-event mode, so an agent knows exactly when to choose this tool over 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 annotations already declaring readOnly/openWorld/idempotent, the description still adds substantial behavioral context: exact response segments, per-opportunity fields (edge_pp_net, kelly fractions, spreads), a 24h-move warning that an edge may already be priced in, the per-leg Kelly design quirk for partition arbs, diagnostics funnel counters, and 1h caching keyed on all knobs. No contradiction with annotations.

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

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

The opening is front-loaded and every cluster of information is dense, but the description is a single wall-of-text paragraph with all-caps segments and parentheticals that are hard to scan. Some details (per-sport alpha values, 'gates relaxed Run 8' history) are irrelevant for tool selection or invocation and make it longer than needed.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It fully specifies the top-level by_segment structure, fed_candidates/fed_note, _diagnostics with funnel counters, the fields on every opportunity, and how all nine knobs affect results. An agent has enough to call the tool and interpret its output correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by grouping knobs into 'TRADEABLE-EDGE KNOBS,' explaining that min_liquidity/max_spread_pp drop unrealizable edges, clarifying that min_partition_leg_kelly applies to per-leg Kelly instead of parent-level, and noting that caching is keyed on all knobs. This is meaningful extra context without restating defaults.

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

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

The opening sentence states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The intended use case is explicit ('what should I bet on today'), and the detailed model-family breakdown makes the tool's role unmistakable, distinguishing it clearly from arbitrage or tracker siblings even without naming them.

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 when-to-use context: agents discover daily opportunities without paging hundreds of markets. It also explains the tradeable-edge knobs and why Fed bets are excluded, but it never explicitly names alternative tools or states when to prefer them, leaving some routing to inference.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive. The description goes well beyond annotations by disclosing concrete behavioral traits: snapshots are written only on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage rather than intraday, and expired opportunities are those gone from the latest snapshot. No contradiction exists.

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

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

The description is long but densely informative and well-structured into purpose, arguments, response shape, and limits. Every clause carries operational value, such as the sign convention for edge_pp_net, the median lifespan as a competition clock, and snapshot date gaps. This is not padding; it earns its length.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It defines tracked[], expired[], snapshot_dates[], explains trend and decay fields, clarifies the sign of edge_pp_net, and covers edge cases like gaps and TTL. For a two-parameter, read-only tool, this is complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the input schema already documents both days and window. The description adds only mild context: days is the lookback with default/max, and window refers to the polymarket_edges window family. This does not meaningfully exceed the schema's explanations, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots and explicitly frames the question it answers: 'how long has this edge existed and is it shrinking?' This is specific and distinguishes it from the sibling polymarket_edges tool, which presumably provides current edge data rather than historical tracking.

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

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

The description does not explicitly say 'use this instead of X', but it strongly implies when this tool is appropriate: for historical edge persistence and decay analysis across snapshot history, whereas polymarket_edges would be the current-edge sibling. It also sets expectations with limits like the 60-day TTL and snapshot-gap behavior, giving an agent enough context to select it correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read-only check. The description adds meaningful behavioral context: it walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), identifies thin legs, and names forced-directional-risk legs. It also explains the dominant loss mode (partial basket fills → unhedged directional position). It doesn't fully disclose rate-limit or data-freshness behavior, but it exceeds the annotation baseline.

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 information-dense but formatted as a single long block of text. It front-loads the core purpose, then covers modes, parameters, and usage guidance. However, it could benefit from paragraph or bullet separation to improve scannability; the density makes it slightly harder to parse quickly.

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

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

Despite lacking an output schema, the description enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites (market or event slug/URL), defaults, and failure semantics. Nothing essential is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds value by explaining the interpretation of size_usd in each mode ('max spend on buys, target proceeds on sells' in single-market; 'settlement notional S (shares per leg; each share pays $1)' in basket), and clarifies that side defaults to auto from partition sum in basket mode. This goes beyond the schema's parameter 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 a specific verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and distinguishes two modes (single-market vs basket). It explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) in its usage guidance, making it easy to select correctly.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable; partial fills create unhedged directional risk), which helps an agent decide between this and 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?

It adds rich behavioral detail beyond the readOnly/openWorld/idempotent hints: exact fee calculation methodology and versions, the limitation that spread-crossing cost is not modeled, clarification that temporal_alignment_unknown is not the sample aligns, and the rule that non-equivalent pairs are never suppressed. This directly changes how an agent would interpret the tool's answers.

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 labeled sections, but it is extremely long, with multiple layers of fee detail, version numbers, and references to internal fleet batches. Every detail is informative, but token cost, and over-specification makes it harder for an agent to find the essential facts.

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

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

With no output schema, the description carries the full burden of explaining the response structure, flags, error cases, fee semantics, resolution comparison, skip counters, and the meaning of aligment fields. It arguably over-explains, ensuring an agent can safely invoke and interpret the tool in non-trivial situations.

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?

Even though parameter schema covers the fields, the description adds crucial semantics: alias and keyword resolution for topic, the difference between exact/alias vs phrase/token verdicts, and how explicit kalshi_event_ticker/polymarket_event_slug override the mapped topic. These behavioral details are not discoverable from the schema alone.

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 first sentence explicitly names the tool's core behavior: cross-venue spread between Kalshi and Polymarket for the same resolving question. It then lays out two precisely defined modes and distinguishes itself by mentioning pre-mapped topics and explicit pairings.

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 describes when to use topic mode vs explicit tickers, and explicitly warns that pre-mapped topics often are not tradeable and that 'phrase'/'token' matches are guesses. It recommends using resolution_audit/resolution_diff when a specific pair of legs is needed, but it does not name alternative sibling tools for similar arbitrage comparisons.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those: the omit-key listing mode, the scoping of memory to an identifier, and the relationship to remember/forget. It does not describe missing-key or empty-result behavior, but annotations lower the burden.

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 sentences with no filler. It front-loads the core behavior, then adds use-case context, then scoping and sibling-tool relationships. Every sentence contributes 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 optional-parameter lookup tool with read-only and idempotent annotations, the description is complete: it covers both invocation modes, gives realistic use examples, explains scoping, and points to related tools. No critical information is missing for an agent to call it correctly.

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

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

The input schema already fully documents the single optional key parameter, including the omit-to-list behavior, so schema coverage is 100%. The description reinforces this but adds little semantic detail beyond what the schema states, aside from concrete examples of what kind of values are stored.

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 leads with a crisp verb and object combination: 'Retrieve a value previously saved via remember, or list all saved keys.' It also names the sibling memory tools (remember/forget) and distinguishes this tool by its read-only lookup role.

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

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

It clearly explains when to use the tool: to look up stored context without recomputing it. It also points to siblings by saying 'Pair with remember to save, forget to delete,' though it stops short of an explicit if-then exclusion like 'do not use for saving.'

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond that: return fields (source, citation_uri, raw payload), the mark_read side effect that affects subsequent calls, and polling suitability. No contradiction with annotations is present.

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

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

Four dense sentences, each earning its place: the opening states the core action, the second details return contents, the third covers filtering and mark_read semantics, and the fourth mentions polling and an alternative endpoint. 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?

Without an output schema, the description compensates by describing the return payload. It also covers filtering, mark_read behavior, polling, and alternative access. Minor omissions like limit defaults and unread_only details are already present in the schema, so the description is nearly complete for a read-oriented tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO format for since, and explaining the consequence of mark_read ('so the next call only shows newer ones'). This exceeds what the schema descriptions alone provide.

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

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

The description uses a specific verb and resource ('Pull fired events from your subscription feed') and clarifies it returns recent alerts from the evaluator's persisted feed. It is conceptually distinct from siblings like list_subscriptions or recent_changes, but it never explicitly names or differentiates those alternative tools, so it falls short of a 5.

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 context: it says polling works fine, explains the mark_read pattern for advancing to newer events, and points to the GET registry.pipeworx.io/alerts.json endpoint as an alternative for scripts and dashboards. However, it does not explicitly contrast with sibling MCP tools, so it lacks 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?

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description still adds substantial context: the parallel fan-out to three sources, the GDELT→GNews fallback trigger conditions, and the USPTO PatentsView sunset with soft-fail behavior. It also discloses the return shape (changes[] grouped by source, total_changes, pipeworx:// URIs). No contradiction with annotations.

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

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

Dense but every sentence earns its place: the leading query examples aid intent matching, the fan-out and fallback details set correct expectations, and the closing sentence routes to the sibling. It is front-loaded with user phrasing before the technical machinery, and the length is proportionate to 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, the description discloses the top-level return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs) so the agent knows what to expect. It covers sources, failure modes, since formats, and the sibling distinction — complete for a high-complexity, multi-source read tool. The only minor gap is that fields inside a changes[] item aren't enumerated.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents type, since, and value. The description adds only a usage preset ('Use "30d" or "1m" for typical monitoring') and restates the since shorthand formats; this is marginal value, not substantial new 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?

States a specific verb and resource: 'change feed for a company in the last N days/weeks/months', backed by six natural-language query patterns. It distinguishes itself from the sibling entity_profile by explicit contrast (time-windowed changes vs static profile), and its multi-source scope (SEC/GDELT/GNews/USPTO) clearly separates it from recent_alerts.

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 names the alternative and the condition that selects it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also prescribes a default window ('Use "30d" or "1m" for typical monitoring') and documents the fallback policy (GDELT preferred, GNews when rate-limited or 5xx).

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, but the description adds far more: ≤60s TTL caching, no push/webhook, empty-window error behavior, court category always empty with unsupported:true, and the honesty contract that releases with zero matched markets are returned rather than dropped. Match labels (true/likely/unclear) and matched_by are disclosed so callers can judge match quality.

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

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

The description is long but well-organized into labeled sections (CATEGORIES, MATCHING AND ITS HONESTY CONTRACT) and front-loads the core purpose. Some clauses are defensive or verbose, such as 'which is an accurate answer, not a bug', but they prevent false bug reports; the density is justified for a multi-source tool with several behavioral caveats.

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?

Covers every behavioral edge case a caller needs: category semantics, empty-window error behavior, match confidence labels, timestamp conventions, and how to verify a match before trusting it. Even with an output schema present, the description adds return-value semantics (markets:[], resolves_on_this_release, matched_by, scheduled_at) and is complete for a complex 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?

Although the schema covers both parameters at 100%, the description adds rich semantic context: what each category means and which underlying source feeds it (fred_release_dates, fomc_calendar, pdufa_catalysts, federal-register), the hours cap and default, and the clock-time conventions for econ vs fed vs FDA/SEC dates. This transforms how an agent should set categories and hours.

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

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

States a specific verb and resource: JOIN of the official release calendar (econ, FOMC, FDA, SEC) against live Polymarket/Kalshi markets, returning scheduled releases in the next N hours and which live markets resolve on them. The 'POSITIONING tool, not a speed product' framing further distinguishes it from arbitrage/spread tools among the siblings.

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

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

Explicitly says when not to use it ('do not use this to try to beat a release') and names concrete alternatives: call resolution_audit / resolution_diff before sizing anything. It also gives category-selection guidance and warns that a short window should be widened rather than assumed empty.

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

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

Annotations already declare the write semantics (readOnlyHint=false), idempotency, and non-destructiveness. The description adds genuinely new behavioral context beyond those annotations: the key-value store is 'scoped by your identifier' and retention is auth-dependent — persistent for authenticated users versus 24 hours for anonymous sessions. No contradiction with annotations.

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

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

Five sentences, each carrying distinct information: purpose, when-to-use triggers, storage model, retention policy, and sibling routing. The opening is front-loaded with the verb and resource, though the final pairing clause ('forget to delete') reads slightly ambiguously despite the sibling literally being named 'forget'.

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 tool with strong annotations and 100% schema coverage, the description covers purpose, usage triggers, memory scoping, and retention semantics. The only notable omission is any statement of the return value or confirmation behavior, which is minor given the absence of an output schema.

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

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

Schema description coverage is 100%, with both key and value fully described in the input schema including format examples. The description reinforces the key-value storage model but adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource — 'Save data the agent will need to reuse later' — and explicitly names the sibling operations ('Pair with recall to retrieve later, forget to delete'), so an agent can distinguish it from recall and forget without opening their schemas. Concrete examples (resolved ticker, target address, user preference, research subject) make the tool's job unmistakable.

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 an explicit trigger condition — 'Use when you discover something worth carrying forward' — with concrete examples of what qualifies and the motivating rationale ('so you don't have to look it up again'). It routes to the related siblings (recall for retrieval, forget for deletion), though it stops short of stating explicit when-not conditions, leaving exclusion largely to inference.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: deterministic regex + vocabulary with no LLM pass, confidence:'low' for unusual clauses, reuse of bet_research's cancellation_rule detector, and the known gap of returning evidence_standard:'unspecified' rather than guessing. No contradiction with annotations.

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

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

The description is long but dense and front-loaded: the first sentence carries the core purpose and output fields, then input semantics, usage context, companion tool, and known gap follow in logical order. Every sentence contributes necessary information with 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?

With no output schema, the description carries the full burden of explaining what the agent gets back. It enumerates the extracted fields, the confidence fallback, the evidence_standard enum values, void_handling reuse, and the known limitation, making the tool fully callable without guessing.

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

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

Schema coverage is 100%, and the description still adds meaningful value: concrete examples for Polymarket slugs and Kalshi tickers, clarification that Kalshi event tickers fall back to a representative market, and why that fallback is safe. This goes well beyond the bare schema properties.

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: 'Extract the settlement clause of a single Polymarket or Kalshi market.' It enumerates exactly which attributes are extracted (source, clock time, precision, evidence standard, void handling) and explicitly distinguishes this tool from resolution_diff and polymarket_kalshi_spread, making sibling differentiation 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 states when to use the tool: before treating a polymarket_kalshi_spread row as real arbitrage. It also names the companion tool resolution_diff for comparing two markets, and explains the Kalshi event-ticker fallback behavior, leaving no ambiguity about when or how 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=falsechers. The description adds important behavioral nuance beyond those hints: it explains the three-way equivalence outcome, the confidence threshold for comparing, and the specific-versus-generic source rule that prevents false conflicts. It also discloses that the tool internally runs resolution_audit, which is useful to set 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 information-dense and front-loaded with the core purpose, but it is long and contains a lengthy parenthetical example and an extended heuristic explanation. Every point is relevant, but the phrasing is verbose and could be tightened or restructured with bullet-like separators. It earns its content but sacrifices conciseness.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: it explains the possible values of `equivalent` (true/false/unclear), mentions `differing_fields`, and instructs the caller to read `raw_clause` in unclear cases. It also covers the non-conflict heuristic. The only gap is not fully specifying the entire output structure or exact field locations, but the guidance is sufficient for the agent to decide when to call 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?

Schema description coverage is 100% with both parameters described as 'First market to compare' and 'Second market to compare.' The description adds that they are markets on either Polymarket or Kalshi and that the tool runs resolution_audit on both sides, which slightly clarifies roles. However, it does not add meaningful detail beyond the schema's enum and nested-object definitions, so a baseline 3 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 opens with a specific verb and resource: 'Field-by-field diff of TWO markets' settlement clauses.' It clearly states that the tool runs resolution_audit on both sides and compares source, settle time, precision, and evidence standard, which differentiates it from the sibling resolution_audit. The three-way return value is also summarized, leaving no ambiguity about the tool's core function.

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 context: 'Use this before sizing a polymarket_kalshi_spread pair as a real cross-venue arb, or standalone to sanity-check any two markets you suspect settle on different things.' This clearly states when to use the tool. It does not, however, explicitly name alternatives or say when not to use it, so it stops short of a full when/when-not guide.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds substantial behavior beyond them: ambiguity handling ("asserts nothing and returns figi_candidates"), graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), explicit reporting of failures ("an identifier that could NOT be resolved is stated explicitly under `unresolved` rather than omitted"), source-labelled identifiers, and the internal cascade across endpoints. No contradiction with the read-only/idempotent annotations exists — the description is consistent with them.

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 definition is front-loaded with purpose and trigger examples, and nearly every sentence earns its place. However, it is a dense wall of prose: the "company" type is explained in a single ~200-word run-on sentence with deep parentheticals (FIGI candidates, bond behavior, ISIN mapping all nested inside), which makes parsing harder than necessary. Reformatting into bullets or shorter sentences would preserve all content while improving readability.

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

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

With no output schema, the description carries the return-value burden, and it largely delivers: it names response elements (figi_candidates for ambiguous matches, `unresolved` for failures, source labels, drug result shape of RxCUI + ingredient + brand + pipeworx citation). For a two-type, multi-endpoint resolver this is thorough. Minor gaps: no concrete example response object, and the drug path is given much less depth than the company path.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema's `value` description is already exemplary. The description adds meaning beyond it: ISIN as a fourth accepted input form (the schema lists only ticker, CIK, or name), the ISIN-to-LEI legal-entity resolution for non-US issuers, and the enrichment-degradation behavior that affects what the returned identifiers mean. It also expands the `type` enum values with concrete output semantics (CIK+ticker+LEI+FIGI vs. RxCUI+ingredient+brand).

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 concrete natural-language triggers ("What's the ticker for…", "find the CIK for…") and then states a crisp verb+resource contract: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates two supported types (company, drug) with distinct output summaries, and differentiates itself from the sibling set by claiming "Use FIRST whenever you have a name but need an ID," which separates it from research-oriented tools like entity_profile and compare_entities.

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 an explicit trigger condition — "Use FIRST whenever you have a name but need an ID" — and even states what it replaces ("replaces 2-3 manual lookups"). The input-format rule ("Pass the ENTITY NAME ONLY… never the question's full noun phrase") is highly actionable guidance. However, it never names sibling alternatives or provides when-not-to-use conditions, so it stops short of full exclusion guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, but the description adds no additional behavioral context beyond repeating the lookup nature. It does not disclose potential network dependencies, rate limits, or that it queries an external service (HackerTarget).

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 extremely short, but this is under-specification rather than conciseness. It is a fragment that lacks structure or explanatory sentences. Every word is essential but crucial information is omitted.

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 tool with one parameter and no output schema, the description fails to convey even the basic input requirement or expected result. It does not state what the input represents, what the output looks like, or any limitations. The overall context is drastically incomplete.

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

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

Schema description coverage is 0% and the description does not explain the 'target' parameter at all. The user is left without knowing whether target is an IP address, domain, or something else, and no format or examples are given.

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 'HackerTarget reverse_dns lookup' clearly indicates the tool performs a reverse DNS lookup, distinguishing it from siblings like dns_lookup (forward DNS) and reverse_ip (IP to domains). However, it is merely a noun phrase rather than a full statement of action, and relies on the tool name for clarity.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, appropriate input types (e.g., IP addresses), or when reverse DNS is preferable to other lookups. No alternative tools are referenced.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. However, the description adds no behavioral context beyond naming the HackerTarget source. It does not mention potential rate limits, external API dependencies, or response format, which are not disclosed by annotations.

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

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

The description is short but under-specified. It restates the tool name and fails to convey necessary details, making it more of a placeholder than a concise, informative description. Every word does not earn its place because the sentence lacks substantive content.

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

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

Given the tool's simplicity (one parameter, no output schema) and the available annotations, the description is incomplete. It does not clarify what input the tool accepts or what output it produces, making it difficult for an agent to select and invoke it correctly without prior knowledge.

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 one required parameter 'target' with no description, and schema description coverage is 0%. The tool description also fails to explain what 'target' should contain (e.g., an IP address) or its format. This leaves the agent without essential parameter semantics.

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

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

The description 'HackerTarget reverse_ip lookup.' is essentially a restatement of the tool name, with only the addition of the data source (HackerTarget). It does not explain what a reverse IP lookup does, what it returns, or how it differs from similar tools like reverse_dns.

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 usage guidance is provided. The description does not state when to use this tool, what input is expected, or how it compares to alternatives such as reverse_dns, dns_lookup, or as_lookup. The agent must infer usage entirely from the tool name.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density per entity. It does not mention cost/rate-limit implications of multi-probe execution, but the core behavior is transparent.

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

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

Three sentences with no filler. The first sentence states the core action, the second explains the mechanism, and the third provides a concrete use case plus output shape. Every sentence earns its place and the key differentiator 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?

With no output schema, the description appropriately explains the return value: a ranked list with score, confidence, and signal density per entity. It covers the main intended scenario and behavior. Minor gaps remain around error cases, cost/rate-limit expectations for multi-probe execution, and explicit alternative guidance, but the description is largely complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and their semantics. The description adds no new parameter-level detail beyond what the schema provides, such as the role of the first entity or the optional Anthropic key. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

The description uses a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes this tool from the single-entity ai_visibility_check by stating that it probes each entity, ranks by score, and surfaces which entity is most/least recognized. The purpose is unambiguous and clearly separated from sibling tools.

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

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

The description gives a concrete use case: competitive AI-marketing audits, with the example 'does Claude know about us as well as our competitors?'. It also names ai_visibility_check as the underlying probe mechanism, implying when this tool is the multi-entity counterpart. It does not explicitly state when not to use it versus compare_entities or other siblings, but the context is clear enough for an agent to route appropriately.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: it is a composite fan-out call across two external services, partial failures degrade gracefully via sources_failed, and bundlephobia's first measurement on a new version can take 5-30s. The latency warning and timeout behavior are exactly the kind of operational context an agent needs before invoking.

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

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

Four dense sentences, each earning its place: purpose, usage triggers, scope/return shape, and failure/latency behavior. The core purpose is front-loaded. It is slightly run-on in the returns enumeration, but with no output schema available, listing the summary fields is justified rather than wasteful.

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 composite tool with no output schema, the description is remarkably complete: it specifies sources, the summary block's fields, per-advisory detail and links, the NPM-only scope, latency behavior, and partial-failure degradation. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 — both package and version are already documented with examples ('@types/node', '18.3.1'). The description adds ecosystem context (npm-only) and reveals that version interacts with the is_latest output field, but it does not materially deepen parameter-level semantics 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 states a precise job — 'Composite "should I add this npm package to my project" check in ONE call' — and names the data sources (deps.dev, bundlephobia) and exact data points (license, advisories, bundle size, dependency count, ESM/tree-shake support). It is clearly distinguishable from sibling research tools like validate_claim, compare_entities, and resolve_entity, none of which evaluate npm packages.

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

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

Gives explicit trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a concrete exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. An agent gets both when-to-use and when-not-to-use with a routed alternative.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description adds genuinely non-obvious behavior: the 200K-char cap with truncation flagged, BGE-base-en embeddings with cosine over 500-char overlapping windows, and offsets enabling verbatim-quote verification. It stops short of a 5 only because how the truncation flag is represented and no-match behavior are left unspecified.

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

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

Four sentences with zero waste: the core operation, the when-and-why, the companion-tool workflow, and implementation constraints each occupy one sentence. The purpose is front-loaded in the first sentence, and no sentence repeats what annotations or schema already provide.

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 correctly carries the burden of explaining return shape — top-N passages with character offsets and similarity scores — and adds windowing mechanics and truncation behavior. For a simple 3-parameter tool with full schema coverage, only edge-case behavior (no matches, exact truncation-flag representation) is missing, which is minor.

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

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

Schema description coverage is 100% — text, query, and limit each have descriptions with defaults, ranges, and examples. The description adds only marginal context (what counts as a fetched record, why the 200K cap and windowing matter) without materially extending parameter semantics, so the high-coverage baseline of 3 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 opens with a specific verb and resource — 'Semantic search INSIDE a fetched record' — and immediately distinguishes itself from fetching tools by requiring 'the text you already pulled.' It names the sibling ask_pipeworx_grounded and specifies its exact output (top-N passages with character offsets and similarity scores), so an agent can tell it apart without opening the schema.

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

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

Explicit when-to-use guidance is present: 'Use when the record is too big to cram into the prompt,' with the reasoning that search_within saves context and returns only the passages that matter. It also routes around a specific sibling, describing the fetch-then-ground workflow with ask_pipeworx_grounded rather than searching the whole document.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description carries little additional burden. The only added context is the source 'HackerTarget,' which hints at an external service but does not disclose behavior such as rate limits or error handling.

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 extremely short but not concise in a useful way; it is a tautological repetition of the name. It provides zero informative content and fails to earn its place.

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

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

For a tool with one parameter and no output schema, the description should explain what a subnet lookup does and what it returns. It does neither, making it entirely inadequate for an agent to select or invoke the tool correctly.

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

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

The schema has one required 'target' parameter with no description. Schema coverage is 0%, and the description does not clarify what 'target' means or how to format it, leaving the agent guessing.

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 is a tautology: 'HackerTarget subnet_lookup lookup' repeats the tool name without explaining what the tool does. No specific verb or resource is described, making it impossible to distinguish from other lookup tools.

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

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

There is no guidance on when to use this tool versus alternatives like dns_lookup, reverse_ip, or geoip. No use cases, prerequisites, or exclusions are provided.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth needs, account-type persistence limits, an SMS phone-verification prerequisite, and a 10/day rate cap. No contradiction with annotations; it enriches them with concrete operational constraints.

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 first sentence carries the core purpose, and each following sentence adds operational detail (account requirement, per-type params, delivery rules). It is dense but not bloated, with only mild redundancy against the schema's parameter descriptions and a 'Supported types' list that omits two of the five enum values.

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 high-complexity tool — five subscription types, three delivery channels, no output schema — and the description covers the essential return value, preconditions, and delivery constraints. Remaining gaps (behavior for patent_grant/clinical_trial, duplicate-subscription behavior) are minor because the schema documents all parameters and the idempotentHint annotation signals retry safety.

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

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

Schema coverage is 100% — the schema already documents all three parameters, including type-specific filter shapes and webhook signing behavior. The description adds interpretive value on top, e.g. items:['5.02'] means officer change and concrete delivery examples, earning one point above the baseline 3.

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

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

States a specific verb and resource ('Create a proactive monitoring subscription to a live-data event stream') and names the returned artifact ('Returns the new subscription id'). The creation focus clearly separates it from lifecycle siblings list_subscriptions and unsubscribe, and from recent_alerts which consumes the feed.

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

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

Gives clear context for use: proactive monitoring of live data, plus a hard precondition ('Requires a Pipeworx OAuth account — anonymous + BYO cannot persist subscriptions'). It also routes feed consumption to the sibling recent_alerts and the public URL, but never explicitly states when not to subscribe or contrasts with list_subscriptions/unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, which covers the safety profile. The description adds valuable context beyond annotations by explaining the tool returns category-bucketed examples derived from the live catalog, includes exact tool and argument shapes, and requires no arguments for a full spread. There is no contradiction with annotations.

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

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

The description is longer than average but every component serves a purpose: common user phrasings, the return format, the tool's role, parameter usage, and when to call it first. The natural language examples at the start and the explicit 'Use this FIRST' directive are front-loaded and impactful. Slight redundancy in listing example topics that appear again in the schema prevents a 5.

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 optional parameter and no output schema, the description fully covers what the tool returns, how to invoke it, how to scope it, and when to use it. It even names the meta-tools it teaches, so an agent would have no difficulty calling it correctly or interpreting its purpose.

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

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

The schema already documents the single optional topic parameter with a complete description and examples, so baseline is 3. The description adds semantic nuance by framing the parameter as 'focus' with domain examples and clarifying that omitting it yields a cross-category spread. This meaningfully enriches the schema definition.

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 precisely identifies the tool as the onboarding entry point for a newly connected agent, explaining it returns category-bucketed example questions across domains and the exact tool and argument shape to answer them. It clearly distinguishes itself from sibling tools like discover_tools by focusing on 'what can I ask' rather than generic discovery, and even names specific meta-tools it teaches.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you,' giving a clear condition for when to invoke it. It also explains how to narrow the scope via an optional topic, but it does not explicitly name sibling alternatives or when to choose them, so it falls just 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal context by naming HackerTarget as the data source, which suggests an external service, but it does not disclose rate limits, failure modes, or other behavioral traits.

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 a single short phrase, 'HackerTarget traceroute lookup.', which is efficient and front-loaded. It wastes no words, though it is slightly under-specified.

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 no output schema and no parameter description, the description is too sparse. It lacks usage context, return value expectations, and any caveats, making it incomplete for an agent to fully understand the tool's behavior beyond its name.

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

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

Schema description coverage is 0%, and the description does not compensate. The parameter 'target' is not explained at all—there is no mention of it being a hostname or IP address. The name itself gives a hint, but the description adds no value 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 it performs a HackerTarget traceroute lookup, using a specific verb ('lookup') and resource ('traceroute'). However, it does not differentiate from similar sibling tools like 'mtr' or 'nping', so it stops short of full distinction.

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 no guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent without context for 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?

Discloses critical behavioral traits beyond annotations: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. This adds real context beyond the readOnlyHint/destructiveHint annotations.

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

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

Two sentences, front-loaded with the action, and no filler. The ownership constraint and deactivation detail each earn their place without bloating the definition.

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

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

For a single-parameter mutation tool with annotations covering safety, the description is fully sufficient. It covers prerequisites, side effects, and downstream visibility of historical data, leaving nothing essential missing.

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

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

The input schema already fully describes the single parameter, including its type and origin ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter-level meaning, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe and list_subscriptions by naming the action of cancellation, and further clarifies the scope with ownership enforcement.

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 use: you must have a subscription id, and you can only cancel your own subscriptions. It does not explicitly name alternatives, but the use case is unambiguous and no exclusions are needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to repeat safety. It adds real behavioral value by explaining that could_not_verify means the check did not happen, carries verification_error{stage,detail}, and must not be presented as evidence. It also mentions performance characteristics (replaces 4–6 sequential calls) and exact percent-delta math, which are meaningful beyond the structured annotations.

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

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

The description is dense but front-loaded with trigger phrases and a clear purpose statement. The later parts about verdict definitions and the 'IMPORTANT for callers' note are useful but could be slightly tightened; overall every sentence earns its place.

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

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

For a claim-verification tool with no output schema, the description adequately explains what returns: a verdict enum, the actual value with a pipeworx:// citation, and reasoning. It also explains the failure mode (could_not_verify vs unsupported). It lacks exhaustive detail on the grounded pipeline's source routing, but that is internal behavior an agent doesn't strictly need to invoke the tool correctly.

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

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

The schema already covers 100% of both parameters with useful descriptions and examples. The description adds context about tolerance_pct's effect on grading and the default cap of 5, which reinforces but doesn't fundamentally extend the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 explicit natural-language trigger phrases and identifies the tool's core action: verifying the truth of a claim against authoritative sources. It also distinguishes the two internal paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for any other factual claim), which separates it from siblings like resolve_entity or ask_pipeworx_grounded.

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

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

It explicitly says to use whenever the agent needs to check whether something a user said is factually correct, and it names the exception path: company-financial claims go through the SEC EDGAR + XBRL fast path, while any other factual claim falls through to the grounded pipeline. It also tells callers what the verdicts mean and which verdict should not be shown as evidence.

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

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

Annotations clearly indicate a read-only, idempotent, non-destructive operation, but the description adds no behavioral context beyond the name. It does not mention the external HackerTarget service, rate limits, or any unusual behavior. The description provides zero value beyond the annotations, so the score is below the baseline 3.

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 extremely short, but this is under-specification rather than effective conciseness. It contains only three words and does not 'earn its place' – it adds no information beyond what is already known from the tool name and title.

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, a single undocumented parameter, and no behavioral context, the description is severely incomplete. The agent cannot tell what the tool does, what input to provide, or what to expect in the response. This is as inadequate as a one-word description.

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 for the required 'target' parameter, and the description gives no hint about what 'target' should be (e.g., domain, IP, or URL). The agent has no information about parameter format or semantics, making this parameter effectively undocumented.

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 'HackerTarget whois lookup' essentially restates the tool name and title. It provides no specific detail about what the lookup entails, what data is returned, or how it differs from sibling tools like dns_lookup or reverse_dns. This is a tautology rather than a clear purpose statement.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or scenarios where this tool is preferred. The agent is left without context for selecting this tool among many similar network-lookup tools.

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