Shodan Internetdb

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

Annotations already declare readOnly, openWorld, idempotent hints. The description adds valuable behavioral context: workers-ai is free, Anthropic requires BYO API key and direct billing, and it details the return format (per-model score, confidence, signals, raw_response plus combined view). 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 well-structured with a clear main action, parameter clarifications, and use cases. Every sentence adds value without redundancy. It is appropriately sized and front-loaded.

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

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

For a tool with no output schema, the description adequately covers the return structure and key behaviors. It explains model options and API key handling. However, it does not detail the scoring algorithm or what 'signals' are, which could be helpful for an AI agent.

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

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

Schema coverage is 100% with parameter descriptions. The description goes beyond by clarifying default model, stating that _apiKey is only needed for Anthropic, and explaining how 'context' helps disambiguate entities. This adds meaningful nuance to the parameter usage.

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

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

The description uses specific verb+resource ('probe LLMs, score visibility') and clearly states the tool's purpose for AI-marketing audits, pre-launch checks, and competitive monitoring. It distinguishes from sibling tools by its unique focus on visibility scoring across models.

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 lists use cases (audits, pre-launch, monitoring) and explains when to use the default vs. Anthropic model. However, it does not explicitly state when not to use this tool or compare it to alternatives like deep_research or 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 mark it read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it fills arguments automatically, returns stable citation URIs, claims confidence levels that should be used critically, and directs users to verify via the primary source. It does not contradict 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 front-loaded with 'PREFER OVER WEB SEARCH' and well organized into policy, examples, alternatives, and caveats. It is longer than minimal, with six examples and a tangential note about opinion-tracking tools, but nearly every sentence earns its place for a broad routing tool.

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 no-output-schema aggregator with six parameters, the description covers purpose, when to prefer it, alternatives, return format, citation behavior, and reliability caveats. An agent has enough information to both select this tool over siblings 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 100% and every parameter is an alias for a single natural-language question; the schema already documents this fully. The description adds examples and trigger phrases but no new parameter semantics, so the baseline score 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?

States a specific verb and resource: it routes a question to one of 5,743 tools across 1,500 verified sources and returns structured answers with pipeworx:// citation URIs. It clearly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and 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?

Opens with 'PREFER OVER WEB SEARCH' and gives explicit trigger phrases and example queries, even saying to use it when web search could also answer. It names alternatives with conditions: deep_research for broad multi-part fan-out, ask_pipeworx_grounded for evidence-grounded follow-ups, ask_pipeworx_beta for per-use invoiced pricing, and recent_alerts/subscribe for opinion tracking.

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

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

Goes well beyond annotations: discloses that candidate routing improvements may be live, that none is active as of 2026-07-26, and that it is a full working router with no fallback. This prevents the dangerous assumption that it delegates to the stable router.

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

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

The description is compact and front-loaded with the beta identity and what is identical. A few redundancies ('identical', 'matches exactly', 'use it exactly like') cost a little, but every sentence adds behavioral or usage value.

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

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

Given rich annotations and full schema coverage, the description provides the necessary beta status, current behavior, and testing context. It references the same response shape as ask_pipeworx, which is adequate but doesn't elaborate on return details since no output schema exists.

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 all six properties explained as aliases for the free-form question. The description adds only 'same arguments' without new parameter semantics, so the 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?

Description states a specific function: a universal router identical to ask_pipeworx with candidate routing improvements, and explicitly differentiates from stable ask_pipeworx by calling itself the experimental edge. It includes concrete scale (5,743 tools) and current behavior (matches ask_pipeworx exactly).

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?

Clearly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains results are compared against the stable router. It does not explicitly state when to prefer ask_pipeworx or avoid the beta, so exclusions are 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?

The description goes well beyond the annotations by disclosing the exact return shape, the refusal reasons, the verbatim evidence behavior, and the extra LLM call cost. It also clarifies that the tool may explicitly refuse when data doesn't directly answer, which is critical behavioral context.

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, front-loading the core purpose and then covering behavior, return contract, refusal modes, and usage tradeoffs. Every sentence earns its place and there is no fluff.

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

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

Despite no output schema, the description provides a full picture of success and refusal responses, source handling, evidence extraction, and cost implications. It is sufficiently complete for an agent to select and invoke the tool correctly in high-stakes scenarios.

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 documents the single required parameter and its aliases with 100% coverage. The description doesn't add parameter-specific semantics, but it doesn't need to because the schema is complete.

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 defines this as a hallucination-resistant answer mode for high-stakes reads, explicitly stating that it extracts answers only from tool results. It differentiates itself from ask_pipeworx by emphasizing groundedness and evidence-based responses.

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

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

The description explicitly states when to use the tool (quoted, cited, or acted-on answers; financial, legal, medical, and public statement contexts) and when to prefer ask_pipeworx for casual lookups. It also mentions the extra LLM call cost as a concrete tradeoff.

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 discloses extensive behavioral traits beyond annotations: classifier fan-out examples, resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuits, closed market blocking, wide-spread warnings), and cancellation rule parsing. This far exceeds what annotations (readOnlyHint, idempotentHint) 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 very detailed and well-structured (with sections like RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR), but it is quite verbose. While each sentence adds value, the length may hinder quick parsing. A slightly more concise version could retain completeness 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?

The description covers all essential aspects: input types, processing logic (classifiers, fan-outs), output shape (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads, cancellation rules), and error states. Given no output schema, the description fully compensates by detailing return fields and conditions.

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 adds meaning beyond the schema: for 'market', it explains it accepts slug, URL, or question text; for 'depth', it describes quick vs thorough; for 'include_raw', it explains response size implications. This helps an agent choose values appropriately.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet via Pipeworx data), and scope (in one call). This distinguishes it from siblings like polymarket_edges or polymarket_arbitrage, which focus on edge tracking or arbitrage.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies when to use the tool but does not explicitly mention when not to use it or direct to alternatives. However, the clear use cases and detailed behavior guide an agent effectively.

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=true, idempotent, non-destructive. The description adds details on data sources (SEC EDGAR, FAERS), sorting by primary metric, and citation URIs, providing behavioral context beyond 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, well-structured paragraph that front-loads key phrases, covers triggers, purpose, type details, ordering, and return value without redundancy.

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

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

Despite no output schema, the description covers return format (paired data + URIs), sorting, and efficiency gains. It adequately addresses the tool's behavior for its complexity, though it could mention rate limits or caching.

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 clear descriptions for both parameters. The description adds context by giving examples of input values and explaining what data each type fetches, enhancing 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 clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with examples of natural language triggers. It distinguishes itself from siblings like entity_profile by emphasizing parallel over sequential lookups.

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 to prefer this tool over sequential single-entity lookups when comparing entities, and provides context for when to use it (comparing 2–5 companies or drugs) with specific data sources per type.

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

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

Even with readOnly/openWorld/idempotent annotations already present, the description adds substantial behavioral context: account and plan requirements, latency expectations, the exact findings packet shape, gaps[] for unanswered facets, never-invented citations, contradictions[] scans, semantic excerpting, and stable fetchable pipeworx:// URIs. Nothing contradicts 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 front-loaded with the account requirement and core behavior, and nearly every sentence adds useful information. However, it is long and contains a garbled tail fragment ('Over broad/multi-topic BREAKING never invents citations...') that hurts structural clarity, preventing a top score.

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 for return semantics and delivers: inputs, output packet contents, citation resolvability, gap behavior, latency, auth/plan constraints, depth differences, and sibling routing. An agent has everything needed to invoke this 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 already covers both parameters at 100%, including a detailed enum description for depth and a clear description for question. The description reinforces that questions can be broad/multi-part and that thorough requires payment, but it adds no new syntax or format details beyond the schema, so the 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 states a specific action: grounded multi-source research across Pipeworx's 1500 structured data sources in one call, decomposing questions into facets and routing to 5,743 tools in parallel. It explicitly distinguishes itself from open-web search and from siblings like ask_pipeworx, so an agent can tell what this tool uniquely 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 gives explicit routing rules: if not signed in, use ask_pipeworx; for a single lookup, use ask_pipeworx. It also states what this tool is best for with concrete examples and clarifies that depth:'thorough' requires a paid plan. This is strong when-to-use and 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 declare the tool as safe, idempotent, and non-destructive. The description adds valuable behavioral details: it returns top-N relevant tools with names, descriptions, and full input schemas (with curated examples), ready to call without a second schema lookup.

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

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

The description is somewhat lengthy but every sentence adds value. It front-loads the primary purpose and provides concrete examples and usage guidance. Minor redundancy in listing domains could be tightened, but overall it's well-structured.

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

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

Given the complexity (6 parameters, no output schema, many siblings), the description fully explains what the tool does, when to use it, what it returns (names, descriptions, schemas), and how it integrates into a workflow (call first). No gaps are apparent.

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 baseline is 3. The description adds context with examples of natural language queries ('analyze housing market trends', 'look up FDA drug approvals') and mentions the limit parameter, providing meaning beyond the schema's terse descriptions.

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

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

The description clearly states the tool finds tools by describing data/task, lists numerous example domains, and explicitly distinguishes itself from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description explicitly states when to use (browse, search, look up, discover tools) and provides a clear directive to call this FIRST when many tools exist, implying it should precede other tool calls. It also implies exclusion for getting a single direct answer.

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 indicate read-only, open-world, idempotent, non-destructive behavior, and the description adds substantial behavioral detail beyond that: 'empty section is a real "no data", not a bug', `sources_used`/`sources_failed` semantics, resolved:false handling for private companies, and the interchangeability of `type` values. This is exactly the kind of runtime behavior an agent needs to interpret results correctly.

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 and a strong routing directive, then covers inputs, outputs, and edge cases in a logical order. It is long and dense, with a run-on fan-out sentence, but every sentence contributes meaningful information and none is 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?

Given the tool's complexity, the absence of an output schema, and the broad multi-source behavior, the description is remarkably complete. It enumerates the data sources, key returned fields, URI format for filings, the meanings of `sources_used`/`sources_failed`, input flexibility, and failure modes. An agent has enough information to select and invoke this tool correctly without needing to inspect further documentation.

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 of the two parameters, including the exact accepted value shapes. The description adds value by giving examples, reinforcing that `value` may be a ticker, CIK, or company name, and explaining name resolution and private-company edge behavior. That goes beyond the schema without being redundant.

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 an explicit, specific purpose: 'full cross-source profile of a US public company in ONE parallel call.' It is packed with concrete invocation examples ('research Acme', 'brief me on Tesla') that make the tool's intent unmistakable. It also differentiates it from single-source SEC/XBRL/news lookups as the holistic alternative.

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 to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also clarifies acceptable inputs (ticker, CIK, company name) and the private-company fallback, so an agent knows exactly when this tool applies and 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 destructiveHint=true and idempotentHint=true, so the description aligns by stating 'Delete'. It adds value with usage-specific behavioral context (e.g., clearing stale or sensitive data) 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, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description is complete: it explains what it does, when to use it, and how to pair it with other tools.

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 does not add new meaning beyond the schema's 'Memory key to delete'. Baseline 3 is appropriate as schema already fully documents 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 clearly states the action 'Delete a previously stored memory by key.' It uses specific verb (delete) and resource (memory by key), and distinguishes from sibling tools 'remember' and 'recall' by name.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember and recall', giving clear context 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard markdown. It lacks error handling or rate limits but is consistent and informative.

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 well-structured paragraph that front-loads the main action, then provides context and use cases. It is slightly verbose but each sentence adds value. Could be more concise.

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 (2 params, no output schema) and rich annotations, the description explains the output format (single text blob) and use cases adequately. It covers the key aspects without significant gaps.

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

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

Schema coverage is 100%, so the description adds marginal value. It rephrases 'url' as 'Full URL of the site to summarize' but does not mention 'max_links' or its default/max values, which are in the schema. 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 clearly states the tool generates an llms.txt file, specifying the format and purpose for AI crawlers. It distinguishes from sibling tools by focusing on a unique output (llms.txt) and use cases like indexing a client's site or auditing a competitor.

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 lists concrete use cases (getting client's site indexed, drafting for own project, auditing competitor). It does not include when not to use or alternative tools, but the scenarios are clear and distinct from siblings.

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

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

Annotations already declare readOnlyHint=true, etc. The description adds value by listing returned fields and mentioning the optional parameter, without contradicting 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 concise sentences: first states purpose and return fields, second provides usage guidance. No unnecessary words.

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

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

Given low complexity (1 optional param, good annotations), the description covers purpose, return fields, and usage guidance fully.

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 does not add meaning beyond what the schema provides for the single parameter; it only implicitly references it via 'active subscriptions'.

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 verb 'List' and resource 'the caller's active subscriptions,' distinguishing it from siblings 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 advises when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel,' which implies the alternatives subscribe and 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 destructiveHint=false. The description adds value by detailing the output (open ports, hostnames, CVEs, CPEs, tags) and clarifying the tool is free and requires no authentication. 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 extremely concise: two sentences plus an example. Every sentence adds unique information (purpose, returns, free/example). No fluff or redundancy.

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

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

Given the tool's simplicity (1 parameter, output schema exists), the description is sufficiently complete. It explains what the tool returns, that it's free, and provides an example. No missing critical context for an AI agent.

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

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

Schema description coverage is 100% with the single 'ip' parameter already described. The description reinforces this by showing an example ('8.8.8.8') and clarifying it's an IPv4 address, providing marginal extra 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 clearly states the tool looks up an IP address in the Shodan InternetDB, specifying the resource (IP address) and the database, with a specific verb ('look up'). It lists the returned data (open ports, hostnames, CVEs, etc.), distinguishing it from sibling tools like 'ai_visibility_check' or 'resolve_entity' which serve different purposes.

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 includes practical usage guidance: 'Free, no API key needed' and an example call. It does not explicitly state when not to use this tool or name alternatives, but the context of siblings (none similar) makes this omission minor.

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 neutral annotations (all false), the description discloses important behavioral traits: the claim_token workflow for anonymous filing and later status checks, the rate limit (5 per identifier per day), and the fact that it is free and doesn't count against quota. No contradiction with annotations 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 fairly long but front-loaded with purpose and usage, and it structures the claim_token workflow clearly. Most sentences serve a function; the 'daily digests / roadmap' sentence is slightly extraneous but not bloated enough to hurt context. Overall appropriate for the tool's complexity.

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

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

Given the moderate complexity (4 params, nested object, no required params, no output schema), the description covers the key return behavior (claim_token), the two-phase feedback checking, rate limits, and scope. A minor gap is the behavior when called with no arguments, but this does not undermine practical completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by advising on message content ('Describe the issue in terms of Pipeworx tools/packs—don't paste the end-user's prompt') and by showing how to use claim_token, though the schema already covers token semantics. This pushes it above the baseline.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature/data_gap, praise) and clarifies it is for feedback, not general questions—clearly distinguishing it from siblings like 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?

Explicit 'Use when...' conditions are given for each feedback type. The description also states when NOT to use it ('ONLY for tools served by this Pipeworx connection') and directs users to file elsewhere for non-Pipeworx tools, providing clear alternatives. Additional guidance on message framing ('don't paste the end-user's prompt') further strengthens usage clarity.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data is self-aggregating, derived from CF analytics-engine, no PII, and cached for 5min-1h. This goes beyond what annotations offer and helps the agent understand the nature of the data.

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

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

The description is concise yet packed with information. It uses a clear structure: initial sentence stating purpose, bulleted use cases, and additional notes on data source, privacy, and caching. Every sentence is earned and adds value.

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

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

Given the simple input schema (one optional parameter with enum), rich annotations, and no output schema, the description fully covers what an agent needs: purpose, usage guidelines, parameter semantics, and behavioral details. It is complete for correct tool selection and 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?

Parameter 'window' has 100% schema description coverage with an enum and text explanation. The tool description adds extra value by explaining the trade-off between shorter windows (hot right now) and longer windows (steady-state demand), which aids in parameter selection.

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 what the tool does: it returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from sibling tools by focusing on trending data from other AI agent calls, using a specific verb 'Returns' and specifying the resource (tools, packs, call volume).

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 lists three concrete use cases (discovering hot data sources, confirming canonical tool, seeing alignment) and explains when to use different window sizes. While it doesn't explicitly state when not to use this tool or compare directly to siblings, the context is clear and helpful.

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, openWorldHint, idempotentHint as true. Description adds significant behavioral context: scanning scope (top 200 markets), partition check threshold (3pp), semantic anchor (0.30 Jaccard), placeholder filter, fill check with CLOB depth. No contradictions.

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?

Description is thorough but long. Front-loads purpose and modes. Every sentence adds value, but some sections could be more terse. However, given complexity, length is acceptable.

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

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

Despite no output schema, description fully explains return structure (opportunities array, partition_check object, fill check results). Covers edge cases like low similarity and placeholder filters. Comprehensive 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?

Schema covers both parameters with descriptions. Tool description adds context: explains event slugs vs topic seed, gives examples, and notes default behavior with no args. This enriches understanding beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage logic.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. It recommends event mode for a specific market and warns against trading when realizable edge is ≤0. Provides alternative tool for custom sizing.

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 extensive behavioral context beyond annotations: caching policy, segment methodology (e.g., Fed bets excluded, placeholder filters), and response structure including diagnostics for empty segments. No contradiction with 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?

Description is overly verbose and technical, which may hinder quick comprehension. While structured into segments and knobs, it could be trimmed without losing essential information.

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

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

Given 9 parameters and no output schema, description fully explains the response structure (by_segment, diagnostics) and key output fields (edge_pp_net, kelly_fraction, etc.), making it self-contained.

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?

With 100% schema coverage, description still adds significant value by explaining parameter interactions (e.g., min_partition_leg_kelly, slippage_pp trade-offs), going beyond basic schema descriptions.

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

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

Description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from sibling tools like polymarket_arbitrage by its specific data source and goal.

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?

Description implies usage for discovering betting opportunities without manual paging, and mentions tradeable-edge knobs, but lacks explicit guidance on when to use this tool versus siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: 60-day snapshot TTL, snapshot triggers on cache-miss, decay from daily closes not intraday, and details on trend computation. 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 comprehensive but somewhat detailed. It is front-loaded with the core purpose and structured into sections (response format, limits). Every sentence adds value, though slight condensation could improve readability for 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?

Given only two optional parameters and no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and includes important limitations (TTL, snapshot frequency). It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default values (days: 14, window: '1wk'), the clamp range for days (2-30), and explains the window families (24hr, 1wk, 1mo). This provides meaning beyond 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 description clearly states that the tool provides edge persistence and decay telemetry, answering the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and decay analysis.

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

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

The description implies usage for evaluating edge longevity and decay, not for real-time or intraday analysis. It provides context on when to use (e.g., comparing a fresh wide edge vs. an old one) but does not explicitly exclude sibling tools or list alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds behavioral details like walking the order book ladder, returning fields (top_of_book, vwap_fill_price, slippage_pp), and warnings about forced directional risk and thin legs. While not missing, it adds value beyond 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 lengthy but well-structured with bold headers for sections, front-loaded purpose, and no redundant sentences. Every sentence adds necessary context for a complex two-mode tool. Slightly verbose but justified by complexity.

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

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

Given no output schema, the description lists key return fields for both modes, explains the logic, and warns about pitfalls. It covers both single-market and basket modes comprehensively, though missing explicit error handling or edge cases. Still highly complete for agent 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 description coverage is 100%, but the tool description provides additional context for size_usd (interpretation difference between single-market and basket), side defaults, and the distinction between market and event parameters, which enhances understanding 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 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly positions itself as a pre-action check for sibling tools like polymarket_arbitrage and polymarket_edges, which sets it apart.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills convert arbs into directional risk, providing clear when-to-use guidance and reasoning.

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 and idempotent, and the description adds substantial behavior beyond that: matching uses keyword/word overlap, pairing is never verified against a shared resolution source, unclassified legs are never paired, temporal_alignment null means uncomputable rather than aligned, and all spreads are gross because Kalshi fees are not modeled. 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 front-loaded with purpose and modes and uses ALL-CAPS section labels, but it is very long and somewhat repetitive (for example, temporal_alignment_unknown and pre-mapped ≠ tradeable are emphasized more than once). Almost every sentence carries safety-relevant information, yet it could be tightened without losing meaning.

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, the description is exceptionally complete: it explains the response shape, the meaning of compatibility codes, per-pair flags, skipped comparisons, temporal alignment semantics, fee treatment, and failure modes. An agent has enough information to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real semantics: topic is a curated shortcut list, explicit parameters override the topic-mapped side, and both modes execute the same matcher with the same disclosures. This is more than the schema alone provides, though not by a large margin.

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 specifies a precise purpose: computing the cross-venue probability spread between Kalshi and Polymarket for the same resolving question. It defines the two modes and makes clear the output is a spread (Kalshi minus Polymarket), not an arbitrary comparison, and even distances itself from a tradeable arbitrage edge.

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 states when the tool is appropriate (same resolving question, equivalent bet shapes) and explains both invocation modes, including when to use explicit ticker/slug overrides. However, it never names sibling tools such as polymarket_arbitrage or states exclusions/instead conditions, so the cross-tool routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all saved keys. This supplements the annotations nicely.

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, front-loading the core action. Every sentence adds value: first sentence states the two modes, second gives usage context, third provides scope and pairing. No unnecessary words.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers the two use cases, scoping, and related tools (remember, forget). It is sufficiently complete for the complexity level.

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?

With 100% schema coverage for the single parameter, the description reinforces and adds context about omitting the key to list all keys. The schema's description ('Memory key to retrieve (omit to list all keys)') is already clear, and the description aligns well.

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 'retrieve' and 'list' with clear resources (saved values/keys). It distinguishes from siblings by explicitly pairing with 'remember' and 'forget', making the purpose unambiguous.

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

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

The description advises using the tool to look up previously stored context without re-deriving it. It explains the two modes (single key vs listing all keys). While it doesn't explicitly state when not to use it or compare to alternatives beyond siblings, the guidance 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining that setting mark_read:true flags events as read to affect subsequent calls, and that the feed is persisted. No contradictions.

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 main action, uses 4-5 efficient sentences with no redundancy. Every sentence adds value.

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

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

Despite no output schema, the description explains the return format (source, citation_uri, payload). All parameters are implicitly covered, and the tool's behavior with polling and mark_read is fully described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the purpose of mark_read (next call shows newer events) and the returned fields, though it omits limit and unread_only from the prose.

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 starts with 'Pull fired events from your subscription feed,' using a specific verb and resource. It details the returned fields (source, citation_uri, payload) and filtering options, distinguishing it clearly from sibling tools like list_subscriptions.

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 states 'Polls work fine' and provides an alternative access method via GET endpoint, giving context for when to use this tool vs. scripts/dashboards. However, it does not explicitly exclude other sibling tools, though none directly compete.

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 indicate safe, idempotent, read-only behavior. Description adds context: fans out to multiple sources, mentions fallback logic and soft-fail for USPTO, and describes output structure. No contradictions observed.

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?

Description is thorough but efficient; front-loaded with example queries and key constraints. Every sentence provides useful information, though it could be slightly more concise.

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 no output schema, the description covers return structure (changes[] grouped by source, total_changes, pipeworx:// URIs), sources, fallback, date formats, and sibling distinction. 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?

Input schema covers all 3 parameters with descriptions (100% coverage). The description enhances with examples like '2026-04-01' or '7d' and suggests typical usage ('Use "30d" or "1m" for typical monitoring'), adding 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's a change feed for a company in a time window, with examples like 'What's new with X'. It explicitly distinguishes from sibling entity_profile, which is for static profiles.

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

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

Provides explicit guidance on when to use (change feed over a window) and when not (use entity_profile for static profile). Also details sources and fallback behavior (GDELT→GNews), which helps the agent decide.

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 behavioral details beyond annotations: scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. Consistent with annotations (write, non-destructive, idempotent).

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?

Single concise paragraph that front-loads the main purpose, then provides usage guidance and behavioral details. Every sentence adds value without redundancy.

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

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

Given the simplicity of a key-value write tool and the presence of idempotentHint, the description covers the essential aspects (scope, persistence, companions). Does not specify return value, but that is acceptable for a write operation without 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 covers both parameters with descriptions. Description adds value by providing example keys (subject_property, target_ticker, user_preference) that clarify naming conventions, enhancing 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?

Clearly states the tool saves data for reuse across conversations or sessions, with specific examples. Distinguishes from sibling tools recall and forget by naming them as complementary actions.

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 'Use when you discover something worth carrying forward' and explains the benefit of not having to look it up again. Names recall and forget as partners, providing clear context for when to use this tool.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive, so the bar is lower. The description goes well beyond that by disclosing cascading internal lookups, graceful degradation when LEI/FIGI enrichment is unavailable, ambiguous-match behavior with `figi_candidates`, explicit `unresolved` fields, and source labelling. This gives agents a realistic model of tool behavior beyond the annotation 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 and dense, but it is front-loaded with purpose and trigger examples, then structured by entity type. It contains a few sprawling parentheticals and explanatory asides that could be tightened, but nearly every sentence adds necessary detail for correct invocation. It is more verbose than ideal yet earns most of 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?

With no output schema, the description must carry the burden of explaining return behavior. It covers what identifiers are returned, how ambiguity is handled, the meaning of `unresolved`, source attribution, and degradation fallbacks. Combined with the rich parameter guidance, an agent has enough information to invoke the tool correctly and interpret its results.

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 gives useful descriptions, but the tool description adds substantial semantics: concrete examples for ticker/CIK/name, the warning about trailing security-class words for bonds, the distinction between brand and generic drug names, and the directive to pass only the entity name. This significantly enriches parameter understanding 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 uses a specific verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates example queries, supported types, and explicitly contrasts with sibling tools by stating 'Use FIRST whenever you have a name but need an ID.' This makes the tool's unique role 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?

It provides strong when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' plus concrete examples of triggering phrases and an explicit note about the type of input to pass ('Pass the ENTITY NAME ONLY'). However, it does not name specific sibling alternatives or state when NOT to use this tool in favor of others, so the exclusion guidance is incomplete.

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 probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density. Annotations already provide readOnlyHint and idempotentHint; description adds process detail without contradiction.

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

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

Two concise sentences front-loading the purpose and outcomes, with zero wasted words.

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

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

Description covers return format (ranked list with scores) adequately given no output schema. Lacks mention of constraints (e.g., entity count 2-8) but schema handles that. Good overall completeness.

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 parameters are well-documented. Description adds no extra parametric detail beyond what schema provides, resulting in baseline score.

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

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

Description clearly states it compares AI visibility across multiple entities, ranks by score, and surfaces most/least recognized. Differentiates from sibling 'ai_visibility_check' (single entity) and generic '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?

Explicitly suggests use for competitive AI-marketing audits. Lacks explicit when-not-to-use or alternatives, but usage context is clear given sibling tool names.

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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 a single paragraph that contains substantial information but is well-structured with the first sentence summarizing purpose. It could be slightly more concise or use bullet points, but it remains informative without excessive verbosity.

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 comprehensively lists the return fields (summary block, advisories, links, alternative versions) and explains partial failure behavior and ecosystem limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, with clear parameter descriptions. The description adds minor context (e.g., scoped packages accepted, defaulting to latest version) but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's composite purpose: a single call to evaluate adding an npm package by checking license, advisories, version history, and bundle size. It also differentiates from sibling tools by noting the npm-only scope and providing an alternative for other ecosystems.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and when not to use (PyPI, Maven, Cargo, Go should use deps.dev directly), providing clear context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond by disclosing the underlying model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and a hard cap of 200K chars with truncation and flagging. 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 three concise sentences. First sentence states the core purpose. Second provides usage guidelines and benefits. Third gives technical details. No unnecessary words; 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?

No output schema, but the description explains what is returned (top-N passages with character offsets and similarity scores). It covers input limits (200K chars), model details, and pairing with a sibling tool. For a semantic search tool with no output schema, this is complete.

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

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

Schema has 100% coverage with descriptions. The description adds context for each parameter: 'text' is document text, 'query' is natural language with examples, and 'limit' is max passages. It explains the purpose beyond the schema, but does not provide default values or detailed syntax.

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 verb 'semantic search' and the resource 'inside a fetched record'. It distinguishes from siblings by referencing 'ask_pipeworx_grounded' and explaining that it saves context by returning only relevant passages. Highly specific with details on outputs (passages, offsets, scores).

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns relevant passages). It does not explicitly state when not to use, but the guidance 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?

Description adds significant behavioral context beyond annotations: OAuth requirement, type-specific parameters, delivery channel behaviors (email templating, SMS cap, webhook signing and auto-disable), and that subscription ID is returned once. 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 well-structured with clear sections (requirements, types, delivery) and uses examples effectively. It is slightly lengthy but every sentence adds value. Could be tightened slightly, but remains clear and informative.

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

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

Given the complexity (3 params, nested objects, multiple types, no output schema), the description is complete. It covers all type-specific parameters, delivery nuances, limitations (SMS cap, webhook auto-disable), and indicates the return value (subscription ID). No missing context.

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

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

Schema coverage is 100%, but the description adds extensive meaning: explains the type enum values with concrete examples, details the structure of params for each type, and elaborates on delivery channel options with constraints (phone verification, webhook signing). This significantly aids correct parameter usage.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by describing its creation functionality.

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 context for when to use: requires a Pipeworx OAuth account, lists supported types with examples, and details delivery channels. It does not explicitly state when not to use it or mention alternatives like using list_subscriptions for existing subscriptions, but the context is sufficient for an AI agent.

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

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

Annotations already indicate safe read-only behavior. The description adds that it returns category-bucketed examples with exact tool/argument shapes from the live catalog, and explains the effect of omitting vs providing the topic argument.

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

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

The description is well-structured, front-loaded with trigger phrases, and contains all necessary information without being overly 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?

Given the simplicity of the tool (one optional parameter, no output schema), the description covers purpose, trigger phrases, output categories, and parameter behavior. It is sufficient for an onboarding 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% with a clear description. The description adds context by explaining the default behavior (full spread) when topic is omitted and gives example values.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx onboarding, lists the categories, and distinguishes it from siblings like ask_pipeworx and entity_profile. It uses specific verbs and resources.

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

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

Explicitly says to use this FIRST when not knowing Pipeworx capabilities, and provides trigger phrases. Could explicitly mention not to use when already having a specific question.

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?

Description adds value beyond annotations by detailing ownership enforcement, deactivation vs deletion, and link to 'recent_alerts'. It is consistent with annotations (idempotentHint, destructiveHint) and explains the mutation behavior clearly.

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

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

Two concise sentences with no waste. First sentence states action and constraint, second explains effect on data. Perfectly structured for quick comprehension.

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

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

For a simple mutation with no output schema, the description covers ownership, permanence of deactivation, and where to find historical data. All necessary context is provided.

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 already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add new parameter information beyond the schema, so baseline score 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?

Description clearly states 'Cancel a subscription by id', naming both the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation and deactivation behavior.

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?

Description notes ownership enforcement and that the row is deactivated not deleted, guiding proper use. It mentions that historical events stay available via 'recent_alerts', suggesting an alternative for history. However, it could explicitly state when not to use this tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses crucial behavioral details: the verdict types returned, the meaning of 'could_not_verify' (with verification_error{stage,detail}) as an absence of evidence, and the fact that unsupported means no source covers found. It also reveals a performance benefit ('Replaces 4–6 sequential calls'). This is substantial behavioral context that annotations alone do not 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 moderately long but well-structured: it opens with actionable example phrasings, states the core purpose, explains the two processing paths, and wraps up with an important caller warning. Each section earns its place, though the list of example queries could be slightly trimmed. It is not overly verbose for the tool's complexity.

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

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

With no output schema, the description fully accounts for return values (verdict, value with citation, reasoning) and error handling ('could_not_verify' vs 'unsupported'). It also covers the tool's scope, routing logic, and performance characteristics, making it self-contained for an agent to decide and invoke correctly. Complexity is high and the description meets that bar.

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. The description does not add parameter-specific semantics beyond the schema; it merely mentions 'exact percent-delta math' and gives examples of the claim parameter. Since the schema already fully describes both parameters (claim and tolerance_pct), the description provides marginal added value for this dimension.

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 explicitly names the tool's purpose: 'natural-language claim verification against authoritative sources' and provides multiple example query forms ('fact check', 'verify the claim that...'). It further differentiates between two internal processing paths (SEC EDGAR for company-financial claims vs. grounded pipeline for any other factual claim), making the tool's scope precise and distinct 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 states clearly 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing for company-financial vs. other claims, which clarifies when the tool is appropriate. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks explicit exclusion/exclusion guidance.

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