Shodan Internetdb

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: it probes one or more LLMs, returns per-model results (score, confidence, signals, raw_response) plus a combined view, and specifies that the default model is Workers AI and that Anthropic requires an API key. 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 sentences, tightly written with no filler. The first sentence states the core action and output. The second adds model details and the API key condition. The third lists use cases. It is front-loaded and 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?

Given the tool's moderate complexity, the description covers all essential aspects: what it does, what it returns (including detailed per-model structure), default vs. optional models, and use cases. There is no output schema, but the description explicitly states the return format. Combined with good annotations and full schema descriptions, no gaps remain.

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

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

Schema coverage is 100%, so all parameters are described in the schema. However, the description adds meaningful context beyond the schema: it gives examples for 'entity', explains the 'models' default and supported values, clarifies that '_apiKey' is passed directly and only needed for Anthropic, and describes the 'context' parameter's disambiguation role. This enhances understanding.

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: probing LLMs for what they know about an entity and scoring visibility (0-100). It specifies the verb 'probe', the resource (LLMs), and the output (score per model). The description distinguishes it from siblings by focusing on visibility scoring and listing concrete use cases like AI-marketing audits and pre-launch checks.

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

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

The description provides explicit guidance on when to use the tool: for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains the default model and the requirement for an API key for Anthropic. However, it does not explicitly mention alternatives or when not to use it, though the use cases are specific enough.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that it returns structured answers with pipeworx:// citation URIs and fills arguments automatically, providing context beyond the annotations 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?

The description is lengthy but well-structured with clear headings and examples. It front-loads the key message and is informative, though a bit verbose. Every sentence serves a purpose, but slight trimming could improve conciseness.

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

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

Given the tool's complexity with 4,774 sources, the description covers purpose, usage, alternatives, input format, and output behavior. Annotations and schema are rich, so no output schema is needed. The description is fully complete for an AI agent to use effectively.

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

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

Schema coverage is 100% and the description does not add detail about parameters beyond what the schema provides. However, it clarifies that the question parameter expects natural language factual queries, which adds some value. Baseline 3 is raised to 4 due to the contextual examples.

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

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

The description states the tool routes questions to authoritative structured data sources with citations, and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' and resource 'Pipeworx' are clearly defined.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides a long list of use cases (e.g., SEC filings, FDA data). It also tells when to use alternatives: for hallucination-resistant answers use ask_pipeworx_grounded, for broad queries use deep_research, making the guidance complete.

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 details on return format, refusal reasons, and extra LLM call cost, complementing annotations that already indicate read-only, idempotent behavior.

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

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

Well-structured, concise with key purpose upfront, then details on mechanics, return format, and usage guidance.

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

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

Covers purpose, usage, behavior, return values, and refusal reasons; complete for a tool of this complexity despite no 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 coverage is 100% with descriptions for all parameters and aliases; description adds no additional parameter meaning 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, extracting answers only from tool results, distinguishing from similar sibling '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?

Explicitly specifies when to use (high-stakes, answer will be quoted/cited/acted on) and when not (prefer ask_pipeworx for casual lookups), including refusal reasons.

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

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

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint are all false/true appropriately. The description goes far beyond annotations, detailing internal processes: classifier logic, fan-out to data sources, response shapes, resolver contract (market_match_confidence, alternatives, etc.), safety mechanisms (low-confidence resolution blocking, closed market handling, wide spread warnings), and resolution-rule risk (cancellation rules). 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 very long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). The first sentences capture the core purpose. While dense, every section adds necessary context for a complex tool. Some redundancy exists (e.g., repeated use case mentions), but overall it earns its length.

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

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

There is no output schema, so the description must explain return values thoroughly. It does: result.market fields, result.analysis (model_probability, edge_pp, kelly_fraction_half, 24h-move warning), result.evidence keys, resolver contract (match_confidence, alternatives, suggestions), parent_event extractor, news fields with fallback details, and error/blocking scenarios. It covers all needed context for an agent to use the tool correctly.

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

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

The input schema covers 100% of parameters with descriptions. The description adds value by explaining the 'depth' parameter (quick vs thorough), the 'include_raw' parameter with a rationale for the default (keeps responses under ~20KB) and when to override (recompute deltas, cite specific observations). This enriches the agent's 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 purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The use cases are explicitly listed: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This differentiates it from sibling tools like polymarket_edges or polymarket_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 provides explicit usage scenarios: 'Use for...' and gives numerous examples of fan-out. It does not, however, explicitly state when NOT to use this tool or mention alternative sibling tools (e.g., polymarket_edges for edge detection). The examples are extensive and help guide appropriate use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial context: for companies, pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, pulls FAERS, FDA approvals, trial counts. It also mentions sorting by primary metric and citation URIs. 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 well-structured with a front-loaded purpose using example queries. It is informative but could be slightly more concise (e.g., 'side-by-side comparison' and 'ALWAYS PREFER' are slightly redundant). Overall, 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?

Given no output schema, the description covers return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It is largely complete for a comparison tool, though it could mention error cases or limitations. Still, it meets needs.

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, but the description adds meaning beyond: it explains what 'company' and 'drug' types retrieve, gives examples for values (tickers/CIKs for companies, drug names), and specifies the count range (2-5). This enriches parameter understanding.

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. It provides example user queries and distinguishes between entity types with specific data sources. It also mentions it replaces 8-15 sequential lookups, differentiating it from siblings.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also lists example queries and specifies the entity types, implying when not to use (e.g., single entity lookups).

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 decomposes questions into facets, routes to 4,774 tools in parallel, returns findings packet with evidence/confidence/source/citations/gaps[], and takes 15-60s. Annotations (readOnlyHint, etc.) are consistent and do not contradict description.

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?

Information-dense and front-loaded with critical usage constraints (account required, alternatives). Slightly long but each sentence adds value. Could be more concise but still effective.

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?

Comprehensive for a complex tool: explains output format (findings packet with evidence, confidence, source, fetched_at, citations, gaps), expected latency, and when to expect empty results. No output schema, so description carries full burden and succeeds.

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 full descriptions (depth enum meanings, question as natural language). The MCP description repeats depth explanation but adds context about question decomposition. With 100% schema coverage, 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 it performs grounded multi-source research across 1242 structured data sources. It contrasts with ask_pipeworx and provides specific examples of suitable questions (e.g., 'compare X and Y's regulatory + financial exposure').

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

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

Explicitly says when to use (broad/multi-part questions over structured data) and when not to use (breaking news, single lookup, if not signed in). Provides alternative tools: ask_pipeworx for general use and for current news.

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, destructiveHint=false, so the tool is known to be safe. The description adds valuable behavioral context: that it returns tool metadata with full schemas and curated examples, and that results are ready to call directly. 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 concise, with two sentences. The first sentence captures the core purpose, and the second provides necessary details without extraneous information. 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?

Given the tool's complexity (6 parameters, no output schema), the description fully explains what the tool does, when to use it, what it returns, and how parameters work. It also provides examples in the input schema. The description is complete for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema: it explains the return value (top-N relevant tools with names, descriptions, schemas, examples) and notes that the query parameter accepts multiple aliases (task, q, description, search). This helps the agent understand how to use the parameters effectively.

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: 'Find tools by describing the data or task.' It provides specific examples of domains and explicitly distinguishes itself from sibling tools by positioning it as a meta-tool for discovering others, especially with the instruction 'Call this FIRST'.

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

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

The description gives explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. It also explains what the tool returns, providing clear context for usage.

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

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

Annotations already cover readOnly, openWorld, idempotent. Description adds value by detailing parallel fan-out across SEC, XBRL, USPTO, news, GLEIF; specific return fields (cik, filings with URIs, fundamentals sorted, patents sunset, news fallback). No 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?

Front-loaded with examples and core purpose; well-structured with lists and clear flow. Slightly lengthy but each sentence contributes necessary detail (sources, output specifics, limitations). Efficient for the 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, description covers key outputs (cik, filings, fundamentals, patents, news, LEI) and behavioral notes (sorting, fallbacks, sunset). Lacks exact format specs but sufficient for understanding tool's capability.

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. Description reinforces by specifying ticker or zero-padded CIK and that names not supported, but adds minimal new meaning 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?

Description clearly states 'full cross-source profile of a US public company in ONE parallel call' with specific verb+resource. Distinguishes from siblings by explicitly preferring over chaining single-pack lookups. Provides example queries to illustrate purpose.

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

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

Explicitly states when to use (holistic view) and when not (if only have a name, use resolve_entity first). Also notes limitations (only US public companies, person/place coming soon). Provides clear alternative and context.

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

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

Annotations already indicate destructive and idempotent behavior; the description adds no extra context about side effects or behavior on non-existent keys.

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?

Very concise, two sentences plus a pairing hint, with the action 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 simple one-parameter tool with no output schema, the description covers purpose and usage adequately, though it lacks error handling details.

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

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

Schema coverage is 100% and the description does not add meaning beyond the schema's description of the 'key' parameter.

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

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

The description clearly states the tool deletes a memory by key, which is a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall'.

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 examples of when to use (stale context, task done, clear sensitive data) and hints at pairing with related tools, but does not give clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds process details (fetches the page, extracts title/description/key links, emits markdown) which is valuable context beyond annotations, but does not mention edge cases or potential limitations.

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

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

The description is three sentences, each earning its place: first sentence states purpose and audience, second explains process, third lists use cases. No fluff or redundancy, making it efficient and easy to parse.

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

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

Given the tool's simplicity (2 parameters, no output schema, rich annotations), the description covers purpose, process, and use cases. It does not document return format details or error handling, but for a straightforward tool, this is sufficient. The annotations compensate for missing behavioral safety details.

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

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

Schema description coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add new semantic information beyond the schema, but it reinforces the general purpose. Baseline 3 is appropriate as no additional value is provided.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the resource and action. It distinguishes itself from sibling tools by focusing on a specific output format for AI crawlers, 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 provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) which guide when to use the tool. However, it does not explicitly state when not to use it or compare to alternatives among siblings, but the use cases are sufficient for typical scenarios.

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds behavioral context: returns specific fields, defaults to active subscriptions only (with optional include_inactive). 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?

Two sentences, no fluff. Front-loads purpose, enumerates return fields, gives usage advice. 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?

Simple tool with one param, good annotations, no output schema. Description covers what it returns, when to use it. Could mention that subscriptions are from the system, but it's sufficient.

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

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

Schema coverage is 100% with a clear description for include_inactive. Description does not add meaning beyond what the schema already provides; baseline 3 is appropriate.

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

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

Description clearly states the action ('List') and resource ('the caller's active subscriptions'). Provides a list of returned fields, making it specific. Distinguishes 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?

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe, 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by stating the tool is free and requires no API key, which is important behavioral context. There is no contradiction with annotations.

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

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

The description is extremely concise: two sentences and an example. Every word adds value, and the structure is front-loaded with the core action.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers all essential aspects: what it does, what it returns, how to use it, and a note on authentication. No gaps remain.

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

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

Schema coverage is 100%, and the schema's description for the 'ip' parameter is clear. The description only repeats the example without adding new semantic meaning beyond 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 verb 'Look up', the resource 'IP address', and the data source 'Shodan InternetDB'. It lists specific return types (open ports, hostnames, CVEs, etc.), making the tool's purpose unambiguous 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 provides key usage guidance: 'Free, no API key needed' and includes an example call. While it does not explicitly discuss when not to use the tool or compare with alternatives, the context signals show no directly similar sibling tools, so the guidance is sufficient.

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

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

Beyond annotations, the description discloses rate limits (5 per identifier per day), free usage, and that feedback is read daily. 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 concise (approx. 5 sentences), front-loaded with purpose, and every sentence adds necessary context 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 no output schema, the description fully covers input, constraints, and impact. No gaps in required information for an agent to correctly use this tool.

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

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

Schema coverage is 100%, and the description adds value by explaining enum values with examples and providing formatting guidance for the message parameter.

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

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

The description clearly states the tool sends feedback to the Pipeworx team, listing specific feedback types (bug, feature, data_gap, praise). It distinguishes itself from sibling tools, none of which serve this purpose.

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

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

The description provides explicit guidance on when to use (e.g., 'when a tool returns wrong/stale data') and what not to do ('don't paste the end-user's prompt'). It covers all usage scenarios without ambiguity.

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 derivation from analytics engine, no PII, and caching windows (5min-1h). Annotations already indicate read-only and idempotent; description adds valuable behavioral 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?

Five sentences, each serving a purpose: purpose, returns, use cases, data source, caching. No repetition or fluff, front-loaded with 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?

Despite no output schema, description clearly explains returns (top tools, packs, call volume) and includes caching and use cases. For a simple one-parameter tool, this is thorough.

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 well-described enum for 'window'. The description echoes the schema's meaning but adds little new semantic value, meeting the baseline for high 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?

Description clearly states the tool returns top tools, packs, and call volume, with a specific verb and resource. It distinguishes from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on trending usage data.

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 lists three use cases (discovering hot data, confirming canonical tools, aligning with agent needs). Does not exclude alternatives but provides 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?

Goes far beyond annotations by explaining internal checks (semantic anchor, partition filter, fill check) and response structure. No contradiction with readOnly or 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?

Well-structured with subheadings, but lengthy. Every sentence adds value, but could be tightened slightly. Front-loaded purpose.

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

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

Covers all major aspects despite no output schema. Describes output fields and references fill_check. Minor gap: does not fully specify all possible response fields.

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?

Adds rich context beyond the schema: explains no-arg behavior, event slug usage, topic seed question, and acceptance of full URLs. Schema coverage is 100% but description provides crucial operational details.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools by focusing on arbitrage rather than edge tracking or fill risk.

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 describes three modes (trending_scan, event, topic) with recommendations: event is recommended for a specific market, topic for cross-event scanning. Provides conditions for not trading and references sibling 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (edge_pp_net, slippage), caching at KV level keyed on knobs, and diagnostics structure. 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 well front-loaded with purpose and then provides deep technical details. While comprehensive, it is lengthy and dense; could be more structured with bullet points. Every sentence adds value, but some rephrasing might improve readability.

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

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

Given 9 parameters, no output schema, and rich annotations, the description is remarkably complete. It explains output top-level structure (by_segment, fed_candidates, _diagnostics), caching, filter logic (placeholder-slug filter, partition overround corrections), and diagnostic counters. 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 description coverage is 100% with detailed parameter descriptions (min_kelly, min_edge_pp, slippage_pp, etc.). The tool description mentions tradeable-edge knobs but adds little beyond the schema's own explanations. Baseline 3 applies.

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

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

The description states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes from sibling tools by describing unique model families and output segments (by_segment). The verb 'scan' and resource 'top Polymarket markets' 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?

The description is built for 'what should I bet on today' and details tradeable-edge knobs (min_liquidity, max_spread_pp) for filtering. It provides context on when to use (discovering opportunities) but does not explicitly mention when not to use or compare to sibling tools like polymarket_arbitrage.

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, openWorld, idempotent, non-destructive. The description adds significant behavioral details: data source (daily snapshots), response structure (tracked[], expired[], snapshot_dates[]), and computational limits (decay from daily closes, not intraday). This exceeds 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?

The description is front-loaded with purpose, then details response structure, then limits. Every sentence adds value, though it is moderately long. Could be slightly more concise but 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?

Without an output schema, the description thoroughly explains the return format including the arrays tracked, expired, and snapshot_dates with their fields. It covers all relevant context: limits, data source, and computation. Complete for a tool with two optional parameters.

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 adds default values (days default 14 max 30, window default '1wk') and clarifies the meaning of 'window' as snapshot family. This adds 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 the tool's purpose: 'Edge persistence and decay telemetry' and answers the question 'how long has this edge existed and is it shrinking?' It uses specific verbs and resources, distinguishing it from the sibling tool 'polymarket_edges' which likely provides current edge values.

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

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

The description provides a clear usage scenario: comparing fresh vs old wide edges, implying when to use persistence checks. It also mentions limits like 60-day TTL and decay from daily closes. However, it does not explicitly state when not to use or name alternatives beyond the implied sibling.

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

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

Annotations already declare safe read-only, idempotent, non-destructive behavior. The description adds detailed behavioral context: walks the ladder, returns specific fields like slippage_pp, verdict (clean|degraded|cannot_fill), and warns about forced directional risk and thin legs. 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 information-dense and front-loaded with the core purpose. However, it is somewhat verbose, repeating details about verdict and thin legs in both modes. Could be tightened slightly without losing clarity.

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 thoroughly lists all return fields (top_of_book, vwap_fill_price, etc.) and explains both single-market and basket modes. It covers edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk, making it complete for effective use.

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 all four parameters. The description adds significant value beyond schema: explains default for size_usd (1000, clamp 10–1,000,000), clarifies side behavior in basket mode (auto from partition sum), and specifies mutual exclusivity of market and event.

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 as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, listing exactly what each returns (e.g., 'top_of_book, vwap_fill_price, slippage_pp, shares_filled' etc.). This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns against partial basket fills converting arb into directional risk, providing clear usage 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 indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: explains the delta is a real signal only when bet shapes are equivalent, details safety fields (compatibility_warning, temporal_alignment, skipped counters), and warns about misleading spreads. This goes 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?

Although lengthy, the description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds necessary detail without redundancy. It is appropriately verbose for a complex tool.

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

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

The tool has 3 parameters and no output schema, yet the description fully covers the expected response (leg-by-leg prices, spread data, safety fields) and edge cases (temporal alignment, skipped cross-types). It provides a complete picture for an agent to invoke and interpret results 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%, but the description adds significant meaning: explains the two modes, provides examples for topic values, and clarifies that explicit tickers override mapped ones. It also describes the effect of parameters on the response, such as the compatibility fields.

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

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

Description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts or explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the cross-venue aspect.

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

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

The description explains when to use the tool (to get spreads between venues) and when not to use it (when compatibility warnings fire, indicating no arb exists). It also mentions that most pre-mapped topics return warnings, setting realistic expectations. However, it does not explicitly name alternatives among sibling tools.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. Description adds scoping to identifier and behavior when key is omitted. 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?

Concise paragraph with front-loaded core function. Every sentence adds value: what, when, scoping, relationships. No filler.

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

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

For a simple tool with one optional parameter and no output schema, description covers purpose, usage, scoping, and links to other tools. Complete.

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

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

Schema coverage is 100%. Description explains behavior of omitting key (list all) and gives examples. Adds semantic meaning 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?

Clearly states the tool retrieves a value saved via remember, or lists all keys if omitted. Examples and use cases provided. Distinguishes from siblings like remember and forget.

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 describes when to use (look up context) and pairs with remember/forget. Scoping to identifier is mentioned. Lacks explicit 'when not to use' but context is 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining pollability, the effect of mark_read on subsequent calls, and the existence of an HTTP endpoint, providing deeper behavioral context 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?

Four sentences, each adding distinct information. Some slight redundancy (first two sentences both describe the result), but overall efficient and well-structured. Front-loaded with the primary action.

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 5 parameters and no output schema, the description thoroughly explains the return fields (source, citation_uri, raw payload), filtering, mark_read behavior, and even an alternative access method. It leaves little ambiguity about what the tool does and how to use it.

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

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

Schema coverage is 100% with inline descriptions. The description adds extra meaning: example filter values like 'sec_8k', clarifies that 'since' is an ISO timestamp, and explains that mark_read flags events as read. This goes beyond the schema's formal definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb ('Pull') and resource ('fired events from your subscription feed'). It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieving triggered events.

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 guidance on when to use: filtering by type/since, setting mark_read, and notes that polls work fine. Also mentions an alternative endpoint for scripts/dashboards, indicating awareness of other access methods. No explicit 'when not to use', but sufficient context.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds substantial behavioral detail: fans out to three sources, GDELT preferred with GNews as fallback, USPTO soft-fails until reactivated, date parsing (ISO or relative), and return structure with citations. 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?

Single dense paragraph that efficiently conveys purpose, source behavior, date formats, output summary, and alternative tool. No filler; 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 fully explains return format (changes grouped by source, total_changes, citation URIs). Covers edge cases like fallbacks and soft-fails. Complete for a complex multi-source 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 descriptions for all three parameters (type, since, value). Description adds a minor suggestion ('Use 30d or 1m for typical monitoring') but does not substantially expand meaning beyond the schema.

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

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

The description clearly states the tool aggregates recent changes for a company from multiple sources (SEC, GDELT/GNews, USPTO) using examples like 'What's new with X'. It distinguishes from sibling 'entity_profile' by explicitly recommending it for static profiles instead.

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 query examples, explains when to use (recent updates in a time window), and contrasts with sibling 'entity_profile' for static data. Also describes fallback behavior for source failures (GDELT→GNews on rate limit/5xx) and soft-fail for USPTO.

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 beyond annotations by specifying key-value pairing, scope by identifier, and persistence details (authenticated vs anonymous 24h). Annotations already idempotent and non-destructive; description adds valuable 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?

Four sentences, each delivering distinct value: purpose, usage timing, storage details, pairing. Front-loaded with core action. No redundancy.

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

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

Thoroughly covers purpose, usage, storage semantics, session behavior, and related tools. Simple tool needs no more.

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; description adds example keys but no additional semantic depth beyond reinforcing schema meaning. 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 saves data for reuse later, with specific examples (ticker, address, preference). It distinguishes from siblings (recall, forget) by mentioning pairing.

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 mentions complementary tools (recall, forget). Lacks explicit 'when not to use' but provides strong contextual guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by disclosing that each call cascades through multiple internal lookup endpoints, replacing 2-3 manual lookups. No contradictions with annotations.

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

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

The description is a single well-organized paragraph that front-loads key examples and usage guidance. Every sentence adds value, though it could be slightly more structured with bullet points for the two entity types. Still efficient and clear.

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 (two entity types, each returning multiple fields including citation URIs), the description fully explains return values and behavior. No output schema exists, so the description compensates well by detailing what each call returns. It also sets expectations for cascading lookups.

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 schema covers 100% with descriptions. The tool description enriches this with examples (ticker, CIK, name) and notes auto-disambiguation for company type. For drug type, it mentions brand/generic names. This adds practical context beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with concrete examples like 'ticker for…', 'CIK for…'. It distinguishes itself by being the first step when other tools require IDs, setting it apart 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 explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It lists supported types and what they return, but does not explicitly discuss when not to use it or compare to alternative tools like entity_profile.

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, destructiveHint=false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. 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?

Four sentences front-loaded with purpose, followed by mechanism and use case. Every sentence adds value without redundancy. Very concise and 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 tool's complexity (multi-entity comparison) and lack of output schema, the description adequately explains the return format (ranked list with score, confidence, signal density) and internal behavior. It does not cover error handling or edge cases, but the annotations and schema compensate.

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. The description adds beyond schema by stating the first entity is treated as the 'subject' for narrative, which clarifies ordering. This provides meaningful additional 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 verb 'Compare' and resource 'AI visibility across multiple entities side-by-side', distinguishing it from the single-entity sibling 'ai_visibility_check'. It specifies ranking, surfacing most/least recognized, and provides a concrete use case.

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

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

The description explicitly recommends use for competitive AI-marketing audits and gives an example question. However, it does not explicitly state when not to use it or suggest alternatives for single-entity checks, though the sibling name implies the distinction.

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 safe, idempotent, read-only behavior. The description adds valuable behavioral details: composite fan-out to external services, partial failures degraded gracefully, bundlephobia first measurement latency (5-30s), and return of a 'sources_failed' list. 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 dense paragraph, but front-loaded with the core purpose. It efficiently packs all necessary information without superfluous words, though it could benefit from some structuring (e.g., bullet list for return fields) for easier 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?

Despite no output schema, the description comprehensively enumerates return fields (summary block with 9 items, per-advisory detail, links, alternative versions). It also covers edge cases: scoped packages, partial failures, ecosystem limitations. This is complete for effective agent use.

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 (100%). The description adds semantic value: 'package' accepts scoped packages like '@types/node', and 'version' defaults to latest when omitted. This explains usage 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 it's a composite check for 'should I add this npm package to my project?' and details the specific sources (deps.dev and bundlephobia). This distinguishes it from sibling tools, none of which perform similar dependency 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly defines when to use and when to use 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 read-only, open-world, idempotent, non-destructive. Description goes beyond by detailing the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K) with truncation flag, and output features (offsets, similarity scores). 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 core purpose and then builds context. It is efficient at 4 sentences covering purpose, use case, pairing, and technical details. Could be slightly more concise but remains readable.

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

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

Despite having no output schema, the description covers expected return values (passages, offsets, similarity scores), limitations (200K char cap, truncation flag), and integration advice (pairing with ask_pipeworx_grounded). This is 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 description coverage is 100% for all three parameters (text, query, limit). The description does not add new 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?

The description clearly states the verb 'semantic search inside' and the resource 'a fetched record', with concrete examples (SEC 10-K, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, establishing a unique role.

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

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

Explicitly recommends use when the record is too large for the prompt and suggests an alternative tool (ask_pipeworx_grounded) for a related workflow. It lacks an explicit 'when not to use' but the context is sufficient.

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

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

The description discloses behavioral traits beyond annotations, including the need for a Pipeworx OAuth account, account persistence requirements, rate limits (e.g., 10 SMS per day), webhook auto-disable after 10 consecutive failures, and the return of a new subscription ID. Annotations already indicate idempotence and non-destructive nature, and the description adds significant context.

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

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

The description is well-structured, starting with the main purpose, then listing types and delivery channels. It is fairly concise for the amount of detail, but some examples could be trimmed. Overall, it is front-loaded and every sentence serves a purpose.

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

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

The description covers the tool's operation, input, and output (returns new subscription ID). It also mentions the webhook signing secret delivery. Given no output schema, it provides sufficient context. Minor gap: no details on subscription ID format, but not critical.

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

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

The description enriches all parameters with meaningful examples and context. For 'type', it explains the enum values (e.g., 'sec_8k' with items codes). For 'params', it provides type-specific structures. For 'delivery', it details feed, email, SMS, and webhook options, including signing secrets and verification steps. This adds value beyond the 100% schema coverage.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses specific verbs and resources, lists supported types and delivery channels, and distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 context on when to use the tool, such as requiring a Pipeworx OAuth account and noting that anonymous/BYO cannot persist subscriptions. It also gives examples of supported subscription types and delivery channels. However, it does not explicitly differentiate from alternatives like 'ask_pipeworx' or 'recent_alerts', though the purpose is clear enough.

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

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

Discloses key behaviors: returns example questions from a live catalog, exact tool+argument shapes, and that calling without arguments gives full spread. Annotations already show readOnly, openWorld, idempotent; description adds valuable context beyond these.

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?

Front-loaded with purpose, lists categories, explains value. Slightly long but well-organized and every sentence adds 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 no output schema, the description fully explains what the tool returns (category-bucketed examples with exact tool shapes) and covers the main use case. Sufficient for a simple one-parameter tool.

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

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

Schema coverage is 100% with a clear description of the topic parameter. Description reinforces the parameter's purpose (focusing the spread) and lists example values, adding meaning beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point, listing its specific function (returning category-bucketed example questions with tool+argument shapes) and distinguishing it from sibling tools like ask_pipeworx and discover_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?

Explicitly advises using this tool first when unsure what Pipeworx can do, and explains when to pass the topic parameter. Lacks explicit 'when not to use' but context is 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?

Adds ownership enforcement and deactivation behavior beyond annotations. 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?

Two sentences, front-loaded purpose, no waste.

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

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

Complete for a single-parameter tool: covers purpose, side effects, security, and integration with sibling recent_alerts.

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 100%; description mentions 'by id' but adds no new semantic detail 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?

Clear verb+resource: "Cancel a subscription by id." Distinguishes from siblings like subscribe and 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?

Explicit ownership enforcement and behavior note (deactivated, not deleted). Provides context on when to use, though no explicit alternatives mentioned beyond sibling list.

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 adds meaningful behavioral context: the specific backend (SEC EDGAR + XBRL), output verdict types, inclusion of pipeworx:// citation, and percent delta. 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 a single paragraph that front-loads example query patterns, immediately followed by purpose and scope. Every sentence adds essential information with no redundancy.

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

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

For a tool with one parameter, no output schema, and strong annotations, the description covers all necessary aspects: domain, input expectations, output structure (verdict types, citation, delta), and rationale (replaces multiple calls). No 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% and the single claim parameter has a description. The description adds value by giving example claim phrasings and specifying the domain (company-financial), which helps the agent formulate valid inputs.

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 provides a precise verb-resource pairing ('validate claim'), includes natural-language query patterns, specifies supported claim domain (company-financial via SEC/XBRL), and distinguishes from siblings by mentioning it replaces multiple sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes to company-financial claims. The mention of replacing 4-6 sequential calls implies efficiency advantage over alternatives.

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