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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: routes to one of 5,529 tools, fills arguments, returns a structured answer with citations, and is a single fast call. It doesn't detail rate limits or exact response format, but the annotations plus description provide strong transparency.

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

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

The description is long but front-loaded with the primary directive and fast use case. Every sentence earns its place: it covers when to use, examples, escalation rules, and sibling alternatives. A slightly tighter structure would improve readability, but the content is fully relevant and well-organized.

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 is remarkably complete for a routing tool: it names the supported domains, gives multiple real-world examples, explains the citation URI behavior, describes the default 'start here' positioning, and gives clear escalation guidance to siblings. Even without an output schema, the description fully prepares an agent to select and invoke the 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 description coverage is 100%: all six parameters are aliases for 'question' and are documented in the input schema. The description reinforces natural-language usage with examples but adds little beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states that ask_pipeworx routes questions to the appropriate data source tool and returns structured answers with pipeworx:// citations, distinguishing it from web search. It also differentiates itself from siblings like ask_pipeworx_grounded and deep_research by explaining the escalation path.

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 over web search, provides trigger phrases and concrete examples, and states 'START HERE for most questions.' It also names specific alternatives (ask_pipeworx_grounded, deep_research) and explains when to use them instead, making usage guidance exceptionally clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds context about the experimental nature, candidate routing improvements, and that no candidate is currently active. It also clarifies that this is a full working router, not a fallback stub. This is useful beyond annotations, though it doesn't detail routing behavior further.

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

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

Three sentences, each providing distinct value: beta relation, current state, and usage guidance. It is slightly repetitive (e.g., 'identical', 'same', 'exactly' appear multiple times), but overall well-structured 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 low-complexity tool with a single required question parameter and aliases, the description covers the key context: experimental nature, current equivalence to ask_pipeworx, and that response shape matches ask_pipeworx. No output schema exists, but the explicit reference to ask_pipeworx's response shape mitigates the gap.

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 every parameter (aliases) fully described in the schema. The description adds no extra parameter semantics beyond stating that arguments are identical to ask_pipeworx. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description clearly states that this is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx and the grounded variant, making its 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 explicitly instructs when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx exactly, implying that for stable usage one would use ask_pipeworx itself. This provides clear usage guidance with a named alternative.

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

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

Goes far beyond readOnly/idempotent annotations by detailing the exact returns on success and refusal, listing all refusal reasons, and explaining that extraction uses ONLY the tool result. This discloses the grounding mechanism, confidence/evidence fields, and hallucination-resistance behavior, adding substantial 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?

Dense but every sentence earns its place: purpose, mechanics, return/refusal shape, use cases, and cost tradeoff are all covered in a compact block. No filler or redundancy.

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

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

Despite no output schema, the description fully explains return values, error/refusal behavior, use context, and relationship to siblings. It is self-sufficient for an agent to decide and 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?

The schema already documents all six parameters as aliases for question, with 100% coverage. The description mentions 'fills arguments' but adds no parameter-specific meaning beyond what the schema provides, so 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?

Clearly identifies as a hallucination-resistant answer mode for high-stakes reads, explicitly differentiating from sibling ask_pipeworx by grounding answers in tool results and returning evidence/refusals. The verb+resource ('answer mode' that routes and extracts) and scope (only what the tool result contains) are specific.

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

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

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples (financial, legal, medical, public statements). It also contrasts with ask_pipeworx for casual lookups and notes the extra LLM call cost, providing a clear when-not.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description adds substantive operational detail: it 'never invented' missing answers, returns contradictions[] for standard/thorough depths, emits a resolvable citation_uri only when the source provides one, uses semantic excerpting instead of head-truncation, and discloses latency ranges. This goes well beyond what annotations convey and has no contradiction with them.

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

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

The description is long but every clause carries operational value—account requirements, data-source scope, alternative guidance, depth semantics, citation behavior, and latency. It front-loads the critical sign-in requirement and core value proposition. However, the single-paragraph, semicolon-heavy structure makes it somewhat difficult to scan, preventing a perfect 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably comprehensive. It details the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the explicit gaps[] for unanswered facets, contradictions[], hop fields, depth behaviors, account tiers, and limitations on live-news topics. It even covers edge cases like 'empty gaps[]' when the topic isn't in the structured catalog, leaving little ambiguity.

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 both parameters (question and depth enum) with 100% coverage, so the baseline is 3. The description enriches this by explaining the behavioral difference between depth levels ('standard re-angles unanswered gaps; thorough additionally chases leads') and tying depth to latency. It also adds context that 'broad/multi-part is fine' for the question parameter, justifying a score above 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?

Identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with the explicit clarification 'this is NOT open-web search.' It distinguishes itself from the sibling ask_pipeworx by framing deep_research for broad/multi-part questions over structured data, while ask_pipeworx is for single 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It names alternatives with precise exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx.' Also notes the account/sign-in condition and directs unsigned-in users to ask_pipeworx, making the decision tree very clear.

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

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

Annotations already 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds significant behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) in one parallel call, and discloses that the patents part 'soft-fails until reactivated' due to USPTO API sunset. 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 thorough yet efficient. It starts with usage examples and a preference statement, then lists sources and returned fields. Every sentence is informative. No redundancy or filler.

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

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

Given the tool's complexity (multi-source, no output schema), the description covers all necessary context: acceptable inputs, return content (filings with URIs, fundamentals, patents, news, LEI), limitations (patents soft-fail), and preferred usage. It provides enough detail for an agent to correctly select and invoke the tool.

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

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

The input schema has two parameters with full coverage. The description adds meaning: value can be a ticker or zero-padded CIK, and explicitly says names are not supported, directing to resolve_entity. The enum for type is explained as only 'company' supported. This enriches the schema significantly.

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 clear example queries ('Tell me about X', 'research Acme') and explicitly states the tool's purpose: full cross-source profile of a US public company. It distinguishes itself from sibling tools like resolve_entity by noting that names are not supported and that resolve_entity should be used first if only a name is available.

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 guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use (names not supported) and directs to resolve_entity as an alternative. Input examples and constraints are clearly outlined.

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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds transparency by explaining the safety fields (compatibility_warning, temporal_alignment), how spreads are computed, and when they are meaningless, going well beyond the annotations.

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

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

The description is front-loaded with the core purpose and then details modes and safety fields. While quite long, every sentence adds value and there is no redundancy. It could be slightly shortened but remains efficient.

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

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

Given 3 parameters and no output schema, the description fully covers what the tool does, when it works, and how to interpret results. It explains edge cases (compatibility, temporal misalignment) and response structure, making it complete for agent decision-making.

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%, providing baseline 3. The description adds value by listing the exact 10 topic shortcuts, explaining that kalshi_event_ticker and polymarket_event_slug override the topic mapping, and giving examples, which enhances understanding 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 the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by being the only spread tool for this pair, and details two usage modes and response format.

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 explains when to use (to find spreads) and when not to (when compatibility_warning fires or temporal_alignment is false). It also warns that most pre-mapped topics return warnings, guiding the agent away from false expectations.

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 declare readOnlyHint and idempotentHint, but the description adds significant behavioral context beyond that: it cascades through multiple endpoints, degrades gracefully (EDGAR identifiers still return if GLEIF/OpenFIGI is unavailable), labels each identifier with its source, and explicitly states unresolved identifiers in an `unresolved` field rather than omitting them. These behaviors are not disclosed in annotations and are valuable for the agent.

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 and front-loaded. The opening example queries immediately signal the tool's purpose, followed by a clear 'Use FIRST' directive and a detailed breakdown of supported types. Every sentence adds useful information (sources, degradation, citations), so there is no dead weight, though a more compact organization could be slightly clearer.

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 (multiple entity types, multiple identifier sources, potential partial failures) and the absence of an output schema, the description thoroughly explains return values: exact identifiers (CIK, LEI, FIGI, RxCUI), source labels, citations, and handling of unresolved cases. It also covers edge cases like ticker-implicit security lookup and service unavailability, making it effectively 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 descriptions already cover both parameters (type and value) with 100% coverage. The description adds richer meaning: the 'company' type returns a cross-source identity spine (CIK, ticker, LEI, FIGI), while 'drug' returns RxCUI with citations. It also gives concrete input examples (e.g., 'ozempic', 'metformin') and explains how unresolved identifiers are represented. This exceeds the baseline expected from schema-only coverage.

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

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

The description explicitly states the tool resolves a user-spoken name to canonical/official identifiers, with a specific verb and resource. It also distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID' and providing concrete example phrasings like 'find the CIK for...'.

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

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

The description gives clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also illustrates with example user queries. However, it does not explicitly mention alternative tools or when not to use this tool, so it stops short of full when-not/alternatives coverage.

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.