Tavily

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: the free default model, the BYO-key cost implication for Anthropic calls, and the per-model return structure. 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 three tightly packed sentences: purpose, key configuration, return format, and use cases. No filler or repetition of schema content. Front-loaded with the most important 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 lacking an output schema, the description clearly explains the return structure ({score, confidence, signals, raw_response} + combined). It covers configuration, cost, use cases, and model selection, making it complete for a 4-param tool with strong annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions the default model and _apiKey purpose, but these are already documented in the schema. It adds minimal extra parameter semantics beyond rephrasing what the schema states.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and the deliverable (visibility score 0-100 per model). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on scoring AI knowledge about an entity rather than general Q&A or research.

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

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

It provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool, though it does not mention exclusions or explicit alternatives, which would merit a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the tool's meta-nature: it routes to sub-tools automatically and fills arguments, so the agent should not try to select a source tool itself. It also defines the output contract (structured answer with stable citation URIs) and implicitly discloses a limitation by directing document-grounded questions elsewhere. It stops short of 5 because it does not cover no-match fallback behavior or recency/freshness bounds.

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 most critical routing decision ('PREFER OVER WEB SEARCH') is front-loaded, and each sentence carries distinct information: domain scope, routing mechanism, trigger phrases, examples, then exclusions. There is mild redundancy between the domain list and the 'any factual question' clause, and the example list runs long, but for a tool with more than thirty siblings this density is earned.

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

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

For a one-required-parameter, read-only router with no output schema, the description covers when to use it, how it behaves, its coverage scope, and its return contract. It does not address the ask_pipeworx_beta sibling (stable-versus-beta choice) or the failure mode when no source tool matches the question. These are minor gaps given the simple interface and strong annotations.

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%: all six properties are documented, with five explicitly marked as aliases for 'question'. The description reinforces natural-language phrasing through trigger words and examples but adds no format, length, or syntax constraints beyond what the schema already states. With the schema carrying the parameter documentation, the baseline 3 applies.

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

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

States a specific verb+resource: routes the question to one of 5,767 tools across 1,506 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. The mechanism (route, fill, return) is concrete and mechanically distinct. It names three closest siblings as alternatives rather than leaving the agent to infer differences from the name alone.

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

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

Opens with the highest-priority directive 'PREFER OVER WEB SEARCH' and lists explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') plus six concrete example questions. It closes with three when-not conditions routed to named siblings: deep_research for multi-part fan-out, ask_pipeworx_grounded for document-grounded questions, and tavily_news for subjective breaking-news synthesis. This is comprehensive when-to-use versus alternative 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 establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those hints: beta status, live candidate routing that is currently inactive, the exact equivalence to ask_pipeworx, and the fact that this is a full working router with no fallback. No contradiction with annotations.

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

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

The description is dense but efficient: it packs identity, current runtime state, usage instruction, and fallback behavior into three sentences. The parenthetical is informative rather than filler, though slightly repetitive with the mention of the experimental edge.

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 covers response shape by referencing ask_pipeworx, and it thoroughly explains the beta/candidate behavior, current state, and fallback semantics. It is complete enough for safe selection and invocation, with minor details deferred to the stable tool's behavior.

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 fully documents all six parameters, including the required question and its aliases, with 100% coverage. The description only says 'same arguments' and adds no additional parameter-level detail, which is acceptable because the schema already carries the parameter burden.

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

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

The description clearly identifies ask_pipeworx_beta as the beta version of ask_pipeworx, an identical universal router over 5,767 tools with the same arguments and response shape. It differentiates the tool by its experimental routing status and current equivalence to the stable 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?

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It also clarifies the current no-candidate state. It does not enumerate exclusions or alternatives like ask_pipeworx_grounded, but provides adequate direction for selection.

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

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

The annotations already signal read-only, open-world, idempotent, non-destructive behavior, and the description adds substantial context: strict evidence grounding, explicit refusal paths with reason codes, and the extra LLM-call cost. There is no contradiction with the annotation hints.

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

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

The description is dense and front-loaded, and nearly every sentence adds decision-useful information. It is longer than minimal because it must document output and refusal behavior in the absence of an output schema; some internal lists could be tightened, but it 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?

With no output schema, the description fully specifies the success and refusal response shapes, including refusal reasons. Combined with the usage guidance and cost trade-off, an agent has everything needed to decide when to invoke it and what to expect back.

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%, including aliases for the question parameter, so the schema does the heavy lifting. The description tells the agent the input is a natural-language question but adds no parameter-level detail beyond that.

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

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

The description names a specific mode ('hallucination-resistant answer mode') and contrasts it with ask_pipeworx, stating it 'EXTRACTS the answer using ONLY what the tool result contains.' This makes the tool's job and its differentiation from the sibling unmissable.

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

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

It explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and provides concrete domains. It also gives a negative rule: 'prefer ask_pipeworx for casual lookups,' directly addressing when not to use it.

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

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

Beyond the reliable annotations (readOnly, idempotent, non-destructive), the description discloses a wealth of behavioral traits: low-confidence matches short-circuit with status 'low_confidence_match', closed markets return 'market_closed_or_inactive', wide-spread markets carry 'illiquid_wide_spread', and the resolution-rule risk section explains how cancellation_rule parses void/postponement settlements. It even mentions the 24h-move warning. This far exceeds the annotation hints.

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

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

Although long, every sentence is information-dense and earns its place. The description is well-structured with clear section labels (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and practical fan-out examples. This is appropriately sized for the tool's complexity.

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

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

With no output schema, the description takes on full responsibility for documenting return values, and it does so comprehensively: it specifies result.market fields, result.analysis fields, result.evidence keying, the resolver contract fields (market_match_confidence, market_match_score, alternatives, suggestions), parent_event structure, news fallback fields, and safety statuses. Edge cases like closed markets and wide spreads are covered. Nothing important is left unexplained.

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 has 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw). The description adds minimal new parameter semantics beyond what the schema provides — it repeats that market can be a slug/URL/question text and gives fan-out examples, but does not clarify parameters like depth or include_raw further. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the exact input types (slug, URL, question text), lists classifiers, and gives fan-out examples. This clearly distinguishes it from siblings like polymarket_edges or deep_research.

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

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

The description explicitly states usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to inspect match confidence before trusting results. However, it does not name alternative tools or state 'do not use when...', so it lacks explicit exclusions.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it explains that company type pulls latest 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years, drug type pulls FAERS/FDA/trial counts, results are sorted by primary metric, and output includes paired data with pipeworx:// citation URIs.

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

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

The description is dense but every sentence earns its place: trigger phrases are front-loaded, then each sentence covers a distinct aspect such as data sources, fiscal-year handling, sorting, output format, and efficiency. No filler or redundant schema repetition.

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

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

Despite having no output schema, the description fully explains what the tool returns (paired data + citation URIs), how results are sorted, what data sources are used, and how edge cases like off-calendar fiscal years are handled. This is sufficient for an agent to invoke the tool correctly without further 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?

While the schema already covers both parameters at 100%, the description enriches them by defining what each type actually does: 'company' pulls fundamental financials, 'drug' pulls trial/adverse-event data. It also gives concrete examples ('AAPL','MSFT' / 'ozempic','mounjaro') and explains how values map to tickers/CIKs or drug names.

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

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

The description clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It includes specific verbs like 'compare', 'rank', and 'head to head', and distinguishes itself from sequential single-entity lookups by describing its parallel nature and data sources.

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 ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides example queries. However, it does not name a specific alternative tool for single-entity lookups or give explicit when-not-to-use cases, so the guidance is clear but slightly incomplete.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already establish safety, idempotency, and non-destructiveness. The description goes beyond by disclosing expected latency (15-60s, up to ~90s for thorough), the semantic excerpting of large records, the gaps[]/contradictions[] behavior, the fact that it is grounded (never invents), and the paid depth 'thorough' requiring a paid plan. It doesn't state what happens to a signed-out user beyond suggesting ask_pipeworx, but that gap is minor given the explicit auth note at the start. No contradiction with annotations.

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

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

The description is dense and front-loaded with the account requirement, but it is long, multi-clause, and loosely punctuated, which makes parsing harder. Important behavioral details are packed into a run-on series of sentences with parentheses and semicolons. It earns points for front-loading the critical sign-in gate and placing the most useful 'best for' examples early, but loses points on readability: several sentences are overloaded with caveats, and a single sentence runs from 'Second-hop iteration' through 'fetchable' without a clean stop.

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 2-parameter tool with no output schema, the description covers the main needed context: auth requirements, time expectations, output packet structure, citation behavior, gaps/contradictions, depth variations, and alternatives. It doesn't explicitly say what a signed-out user will see if they call it anyway, nor does it describe output formatting enough for an agent to know how to parse the findings packet. But given the absence of an output schema, the description still delivers the core completeness for selecting and invoking the tool correctly. Slight deduction for the small unaddressed edge cases.

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

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

The schema covers both parameters fully (question description says natural language, broad/multi-part is fine; depth describes enum values and behavior). The description adds extra semantic context by explaining the behavioral meaning of depth choices (quick=3 facets, standard=3 with gap recovery, thorough=6 with iterative hops, paid), which exceeds the schema's compressed field description. It also explains that question is meant for multi-part decomposition, not a single keyword search. Because schema coverage is 100% and the description adds meaningful context on top of that, this deserves 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?

The description uses strong, specific language: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' with explicit examples and a clear contrast to open-web search. It distinguishes itself from siblings by naming ask_pipeworx (single lookup) and ask_pipeworx/ask_pipeworx_grounded for live/broad news, and it describes the tool's core workflow: decomposes questions, routes to tools, returns a findings packet. This is a specific verb+resource+scope definition that lets an agent recognize when to invoke it.

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 when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples, and when-not-to-use with named alternatives: signed-out users should use ask_pipeworx; breaking/current-news topics should prefer ask_pipeworx (live news APIs). It also explains depth tiers and the trade-off between standard and thorough. No ambiguity remains about which sibling to select.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and states results are ready to call directly without a second schema lookup. This goes beyond annotations, though it omits details like rate limits or error handling.

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

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

The description is moderately long but front-loaded with the core purpose, followed by when-to-use, domain list, and return contract. Each sentence contributes value; the domain list is somewhat extensive but helps an agent gauge coverage. No obvious 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?

There is no output schema, so the description appropriately compensates by explaining exactly what is returned: top-N tools with names, descriptions, full input schemas, and curated examples, plus the note that results are directly callable. It also covers when to use it first. It lacks edge-case behavior (e.g., no results found) but is sufficiently complete for a read-only discovery tool with strong annotations.

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 coverage is 100%, with query and its aliases (q, task, search, description) and limit (default 20, max 50) all documented in the schema. The description gives examples and reinforces that query is a natural language description, but it does not add new parameter meanings or usage constraints 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?

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates supported domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes itself from sibling tools like search or search_within by positioning it as a meta-tool for discovering which tools exist. The verb 'discover' is specific and the resource ('tools') is explicit.

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 use it 'when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context. It does not name specific alternative tools, but the 'call this first' guidance implies when not to use it (when you already know the exact tool).

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond them: the full source fan-out, the USPTO sunset soft-fail, sources_used/sources_failed semantics, and resolved:false behavior for private companies. This is transparency well beyond what annotations alone could convey.

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

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

Long but appropriately sized for an eight-source tool with no output schema. The user-intent examples and 'ALWAYS PREFER' directive are front-loaded, and the remaining field catalog is compactly organized with semicolons and CAPS key terms. Every sentence carries informative weight.

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

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

With no output schema, the description must document return semantics, and it does so thoroughly: recent filings, fundamentals, patents, federal contracts, FDA products, hiring, news, and LEI are all listed with their sources and special cases. It also handles expected empty sections, soft-fails, input-resolution behavior, and private-company responses, leaving an agent well-equipped to interpret results.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description earns extra credit by clarifying that type values are interchangeable, CIKs should be zero-padded, names resolve via EDGAR's company-name match, and private entities yield a resolved:false response rather than a failure.

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

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

The description opens with concrete user-phrase examples and states 'full cross-source profile of a US public company in ONE parallel call,' naming a specific verb, resource, and invocation mode. It is clearly distinguished from chained single-pack lookups and from siblings like compare_entities or deep_research.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving both the trigger and the alternative. It also covers edge cases: names resolve via SEC EDGAR, private companies return resolved:false with a notes line, and empty sections are expected rather than failures.

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, idempotent), the description adds concrete behavioral details: strips boilerplate/navigation, returns up to 20,000 characters per page, and accepts both single URL and array inputs. It also notes the API key fallback behavior. 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 with the primary action, and every clause contributes value. No filler or repetition.

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

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

For a simple read-only extraction tool with no output schema, the description covers input formats, processing behavior, output limits, and intended use case. This is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, and the description adds no meaningful parameter-specific information beyond what is already in the schema. The description mentions accepting a string or array, but this is already documented in the schema property description and 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 uses a specific verb and resource: 'Extract clean article text from one or more URLs via Tavily.' It clearly distinguishes from sibling tools like search and search_within by focusing on content extraction rather than search results.

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 clear context with 'Ideal for feeding source pages into an LLM,' which signals when to use. However, it does not explicitly mention when not to use or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already disclose destructiveHint=true and readOnlyHint=false, so the description doesn't need to repeat mutation risk. It adds minor context by mentioning 'sensitive data' and 'previously stored memory', but no additional behavior such as missing-key handling or persistence effects is described.

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, immediately front-loaded with the action, and every word adds value. It is well-structured and free of 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 one-parameter tool with no output schema, the combination of annotations, schema, and description is complete. It explains the operation, when to use it, and its relationship to sibling tools, leaving no significant gaps.

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

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

Schema coverage is 100% and the description's 'by key' echoes the existing parameter description. No new meaning is added beyond what the input schema already states, so a 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?

The description starts with a specific verb ('Delete') and a clear resource ('a previously stored memory by key'), distinguishing it from sibling tools like remember and recall. It unambiguously states what the tool does.

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

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

Provides explicit when-to-use scenarios ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall. Lacks an explicit when-not-to-use statement, but the guidance is otherwise 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, idempotent, and non-destructive behavior. The description adds the fetch-extract-emit process and clarifies the output is a single text blob ready for site-root/llms.txt, which goes beyond annotation-provided safety and adds useful behavioral context.

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

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

The description is concise at three sentences, front-loaded with purpose, then process, then use cases. Every sentence contributes value with no filler or redundancy.

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

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

Given the simple tool, full schema coverage, and strong annotations, the description covers purpose, process, output format, and practical use cases. It is complete for an agent to select and invoke correctly without requiring additional context.

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

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

The input schema covers 100% of parameters with descriptive comments for url and max_links. The description adds little beyond the schema, but the schema already provides full semantics, so a 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?

The description clearly states the tool generates an llms.txt file for any URL, with a specific verb and resource. It details the process (fetches, extracts title/description/key links, emits standard markdown) and distinguishes it from sibling tools by focusing on the llms.txt output.

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 your own project, and auditing a competitor. It gives clear context for when to use the tool, though it doesn't explicitly exclude alternatives or name them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope of 'active' subscriptions. No contradiction found.

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

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

The description is two sentences, front-loaded with the purpose and return fields, followed by usage guidance. Every sentence earns its place with no redundancy or fluff.

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

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

Given the tool has only one optional parameter, rich annotations, and no output schema, the description compensates by listing the return fields and providing usage context. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage for the single parameter include_inactive, with a clear description ('Include cancelled subscriptions in the response (default false)'). The tool description does not add further parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb (list), resource (subscriptions), and scope (caller's active). It also enumerates the returned fields, and the context of sibling tools (subscribe, unsubscribe) makes its purpose distinct.

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

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

The description explicitly tells when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear use cases and implicitly contrasts with the sibling subscribe and unsubscribe 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 only provide negative hints (readOnlyHint:false, etc.), so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...'), adding rich behavioral context 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 lengthy but every clause earns its place: usage triggers, scope exclusion, token flow, rate limit, and cost. It is front-loaded with the primary action and uses compact parentheticals for categories. It is slightly dense, but appropriate for the tool's complexity, so a 4 rather than 5.

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

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

No output schema exists, but the description explains the full feedback lifecycle: what to report, exclusions, expected return (claim_token), how to check resolution, daily rate limit, and cost. It also gives expected message length and category definitions, making it complete 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?

Schema coverage is 100%, so baseline is 3. The description adds beyond-schema value by explaining claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and message guidance ('1-2 sentences typical, 2000 chars max'), which are not present in the schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the tool's verb and resource. It further distinguishes from siblings by stating 'ONLY for tools served by this Pipeworx connection' and explicitly excluding other MCP servers, making its scope 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 usage triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use rule: 'if the tool came from a different MCP server... file it with that server instead,' plus a 'Not sure?' fallback for uncertain agents.

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 and idempotent behavior, but the description adds significant context: the data source (CF analytics-engine), no PII, the return shape (pack, tool, count), and caching windows. This goes well beyond the annotations and helps set expectations.

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

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

The description is front-loaded with a clear purpose statement, then provides return details, numbered use cases, and data characteristics. Every sentence contributes useful information, and the structure makes it easy to scan.

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

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

For a simple read-only tool with one optional parameter and rich annotations, the description covering the output shape, source, privacy, and caching is complete. Even without an output schema, the agent knows what to expect from 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 schema fully describes the 'window' parameter with an enum and meaning, so the baseline is 3. The description only mentions the window in passing and adds a related caching detail, which is marginal extra 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 function: it returns top tools, top packs, and total call volume based on other AI agents' calls to Pipeworx. The verb 'Returns' and explicit output list distinguish it from siblings like discover_tools, emphasizing its self-aggregating nature.

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 ('Useful for...') that tell the agent when to use it, such as discovering hot data sources and confirming canonical tools. However, it does not name alternatives or explicitly state when not to use it, leaving exclusions implicit.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds rich behavioral context beyond that: the 3pp deviation threshold, placeholder filtering logic (PARTITION FILTER), fill check against live CLOB depth, and the meaning of skipped_low_similarity. Also discloses that a signal may be theoretical only ('overround exists only at last-trade, not in the book'). No contradiction with annotations.

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

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

The description is long and dense, but organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and uses bullet-like clarity within prose. Some redundancy exists (e.g., restating that partition_check sums to ~1), but given the tool's complexity, the length is mostly earned. Could be tightened without losing 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?

Without an output schema, the description directly explains the response structure (opportunities[], partition_check, fill_check details) and covers edge cases (skipped_low_similarity, placeholders_filtered, thin_legs). This is a complete picture for the agent to know what the tool returns and how to interpret it, including the crucial warning about realizable edge.

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 description still adds significant meaning by providing example slugs ('fed-decision-may-2026'), clarifying that full URLs are accepted, and explaining the behavioral difference between `event` and `topic` modes beyond their schema descriptions. The description gives concrete use cases and what to expect from each 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 uses a specific verb ('Find arbitrage opportunities') with a clear resource ('Polymarket') and method ('monotonicity violations + partition-sum checks'). It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection, not just edges 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 explains when to use each mode: NO args for trending_scan, `event` for a specific market, `topic` for cross-event scanning. Also mentions alternative tools ('For custom sizing use polymarket_fill_risk') and warns when a signal should not be traded, e.g., 'realizable_edge_pp ≤ 0... do not trade it'.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description goes far beyond by disclosing the internal model families, response structure, caching behavior ('Cached 1h at the KV level keyed on all knobs'), the special partition Kelly behavior, and the 24h-move warning. It also explains why segments may be empty via _diagnostics. This is a model of behavioral 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 very long but every sentence adds value, and it's front-loaded with the purpose. It uses all-caps section markers and parentheses to organize a dense amount of information. Given the tool's complexity (9 parameters, three model families, response details), the length is justifiable, though it could be broken into more readable sections.

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 thoroughly covers the response structure (by_segment, fed_candidates/fed_note, _diagnostics), explains what each opportunity carries, and even tells callers why a segment might be empty. Combined with detailed parameter semantics and annotations, this is a complete picture for an agent to use the tool 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?

The input schema already covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description significantly enhances parameter understanding by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying the special case of min_partition_leg_kelly with partition arbs. This goes well 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It doesn't explicitly distinguish itself from sibling tools like polymarket_arbitrage, but the focus on edge opportunities and the detailed model families make the purpose unmistakable.

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

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

The description gives a clear usage context ('agents discover opportunities without paging hundreds of markets'), explains tradeable-edge knobs and when to adjust them (e.g., 'Set to 2 to require tight books'), and notes exclusions (Fed bets excluded from ranking due to unreliable signal). It doesn't name alternative tools directly, but the guidance is rich enough to know when this tool is appropriate.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals detailed behavior: snapshots are written on cache-miss, gaps in snapshot_dates mean no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes, not intraday. This is substantial context not available in 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 well-structured with clear sections (opening purpose, Args, RESPONSE, LIMITS). It is detailed but every sentence contributes crucial information about data provenance, return fields, and pitfalls. The length is justified by the complexity, and it is front-loaded with the core question it answers.

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. It does so thoroughly, enumerating tracked[], expired[], and snapshot_dates[] with field-level detail (edge_pp_net time-series, trend, decay, lifespan). It also covers limitations like TTL and snapshot gaps, making it sufficiently complete 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% and the schema already explains both parameters (days as lookback with clamp, window as the snapshot family). The description restates these and adds minimal new meaning (e.g., 'max 30' is already implied by 'clamp 2-30'). Thus the description adds little beyond what the schema provides.

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

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

The description opens with a specific verb phrase 'Edge persistence and decay telemetry' and directly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from the sibling tool polymarket_edges by focusing on temporal persistence rather than raw edge 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?

The description conveys a clear use case: when to care about edge age ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also gives LIMITS that help set expectations, but it does not explicitly name alternatives like polymarket_edges for when only current edges are needed.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by disclosing mode-specific behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), the interpretation of size_usd in each mode, and the risk of partial basket fills. No contradiction with annotations exists; the description adds rich behavioral context.

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

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

The description is dense and long, but every sentence provides necessary detail for a dual-mode tool with critical risk warnings. It is front-loaded with the core purpose and then structured by mode, return values, and usage guidance. The length is justified by the complexity; still, some redundancy (e.g., repeating 'top-of-book vs VWAP') could be trimmed.

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

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

There is no output schema, so the description carries the full burden of explaining return values, which it does thoroughly for both single-market and basket modes. It covers required inputs, optional parameters, defaults, edge cases (thin_legs, forced_directional_risk), and actionable usage context. For a complex tool with zero 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 coverage is 100%, but the description adds meaning beyond the schema by explaining how 'market' and 'event' select modes, how 'side' defaults differ by mode, and how 'size_usd' is interpreted (max spend vs target proceeds vs settlement notional). It also mentions the clamp range, which is not in the schema, making parameter usage unambiguous.

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

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

The description uses a specific verb ('checks') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and clearly differentiates between single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation or edge calculation.

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

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

The description explicitly states when to use the tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the consequences of not using it (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk). It also names no alternative tools, but the context is clear and actionable.

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

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

Annotations already indicate read-only/idempotent, and the description goes far beyond them: it exposes compatibility codes, temporal alignment semantics, fee-schedule omission, unclassified leg exclusion, and keyword-overlap matching limits. It also clarifies that null temporal_alignment means unknown rather than aligned. No contradiction with annotations.

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

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

The description is long but structured with labeled sections, and nearly every sentence carries operational caveats or response semantics. It front-loads the core purpose, then layers safety disclosures. Still, the introductory participant-pool explanation could be trimmed without losing essential 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?

With no output schema, the description carries the full burden of explaining return structure, and it does: prices, top_spreads_pp with per-entry flags, compatibility fields, temporal_alignment, fees_note, and skipped counters. Nothing an agent needs to safely call the tool and interpret results is missing.

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

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

The schema already documents all three parameters with 100% coverage, including the topic enum and override relationship. The description adds high-level mode context and says both modes run the same matcher, but does not materially extend per-parameter semantics. With full schema coverage, the baseline of 3 is appropriate.

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

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

The opening clause names the exact resource—cross-venue spread between Kalshi and Polymarket—and the two modes make the operation concrete. It stands apart from sibling Polymarket-only tools by specifying cross-venue comparison. While the description is noun-phrased rather than verb-first, there is no ambiguity about what the tool computes.

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

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

It clearly delineates topic mode for the 10 pre-mapped shortcuts and explicit mode for custom ticker/slug pairings. It warns that pre-mapped topics often return compatibility warnings, which implicitly tells agents not to assume a shortcut yields a tradeable spread. However, it does not name alternative sibling tools or give explicit 'use X instead' conditions.

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

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

Beyond the readOnly/I idempotent annotations, it discloses that memory is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), which is important for data isolation. It also describes the conditional list behavior when the key is omitted, adding 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 concise, front-loaded with the primary action, and every sentence earns its place. It covers retrieval, listing, usage context, scoping, and related tools in just two sentences 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 tool's simplicity, the description covers purpose, usage, scoping, and relationships. It lacks an explicit return format for missing keys, but the annotations and clear examples make it complete enough for effective 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?

The input schema already fully describes the sole parameter key, including the 'omit to list all keys' behavior. The description repeats this and adds examples of key content, but does not introduce new syntax or constraints, so 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?

Clearly states it retrieves a previously saved value or lists all keys when the key argument is omitted. The verb 'retrieve/list' with the resource 'memory key' is specific, and it distinguishes from siblings by explicitly pairing with 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?

Provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the complementary tools remember and forget, giving clear alternatives and implicit when-not (to save, use remember; to delete, use forget).

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 (readOnlyHint, idempotentHint), the description discloses the mark_read side effect (flipping read state) and explains what each event carries (source, citation_uri, raw payload). It also notes the same feed is available via a public URL. This adds substantial context 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?

The description is compact and front-loaded with the primary purpose. Each sentence provides distinct value: what it does, what it returns, how to filter, mark_read behavior, and alternative access. 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 5 optional parameters, no output schema, and rich annotations, the description covers the return payload, filtering, mark_read, and polling/alternative access. It lacks explicit pagination or error-handling notes, but these are minor gaps for a read-only polling 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 descriptions cover all 5 parameters, so baseline is 3. The description adds a concrete type example ('sec_8k') and clarifies the behavioral effect of mark_read, but most parameter meaning is already captured in the schema. It does not fully compensate for the lack of enums or detailed value formatting.

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 'Pull fired events from your subscription feed', which names a specific verb and resource. It clearly distinguishes this from sibling tools like 'recent_changes' by focusing on alerts/subscription 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?

The description gives practical guidance: filtering by type/since, using mark_read to control subsequent reads, and polling. It also mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like list_subscriptions or recent_changes.

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 reveals significant behavioral details beyond the annotations: it fans out to SEC EDGAR, GDELT→GNews (with fallback logic), and USPTO (with a noted API sunset causing soft-fail). This is valuable operational context that annotations 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?

Despite its length, the description is dense and well-structured: it opens with query examples, defines the core behavior, explains internal source fan-out and fallbacks, details the `since` parameter, and closes with a sibling contrast. Every sentence contributes necessary 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?

The description covers the return format (changes[], total_changes, citation URIs), source behavior, parameter formats, and alternative tool usage. Given the tool's complexity and lack of an output schema, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for `since` ('7d', '30d', '3m', '1y') and a usage recommendation, which slightly enhances understanding beyond the schema's minimal definition.

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

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

The description clearly states the tool is a 'change feed for a company' and provides multiple example query forms ('What's new with X', 'updates on Acme') that make its purpose immediately recognizable. It also explicitly contrasts with entity_profile, distinguishing it from sibling tools.

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

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

The description gives explicit when-to-use guidance via the query examples and directly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This covers both when to use and 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?

Annotations show this is a write (readOnly=false), idempotent, non-destructive operation. The description adds useful context: persistence depends on auth (authenticated = persistent; anonymous = 24h) and values are scoped by identifier. It does not explicitly state whether re-saving the same key overwrites the existing value, but overall it exceeds the annotation baseline.

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

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

The description is four sentences, front-loaded with the main action, and each sentence contributes: what it does, when to use it, storage format/scope, persistence, and related tools. No unnecessary 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 2-parameter tool with no output schema, this description is complete: it explains the tool's behavior, gives use cases, describes memory scope and retention, and points to related tools (recall, forget). No meaningful 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?

The schema already fully documents both parameters (key and value) with examples (100% coverage). The description only reinforces that this is a key-value pair, adding no new semantic detail beyond what the schema 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?

The description opens with 'Save data the agent will need to reuse later' and specifies scope across conversation/sessions. It clearly distinguishes from siblings recall (retrieve) and forget (delete) by naming them, making the tool's 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?

Explicitly states 'Use when you discover something worth carrying forward' with concrete examples, and tells the agent to pair with recall/forget for later retrieval/deletion. It lacks explicit when-not or exclusion cases, but the guidance 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 operation as read-only, open-world, idempotent, and non-destructive, so the description does not need to repeat those. It adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, `figi_candidates` on ambiguity, source-labelled identifiers, and internal cascading lookups. This greatly 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 dense and every sentence carries useful information, but it is a wall of text with long run-on clauses and nested parentheticals. The most important guidance is front-loaded with examples and 'Use FIRST', but readability could be improved with clearer separation of scenarios.

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

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

Given the tool's complexity, the lack of an output schema, and the two required parameters, the description is remarkably complete. It covers supported types, input formats, ambiguous-match behavior, unresolved identifier handling, degradation behavior, and the internal cascading nature of lookups. An agent has enough to call this tool correctly across edge cases.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning beyond the schema: how `type` maps to supported sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), how `value` is interpreted differently by type, and specific examples like ticker/CIK/ISIN/brand names. It also warns about bond issuer name formatting, which is crucial for correct invocation.

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

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

The description states a specific verb ('resolve') and resource (named entity to canonical identifiers) and gives concrete example queries. It clearly differentiates from siblings by positioning itself as the first stop when a name needs to become an ID, which is distinct from entity_profile or 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 states 'Use FIRST whenever you have a name but need an ID.' It also provides detailed guidance on what inputs are valid, what entity types are supported, and even a negative example for bonds where trailing security-class words should be omitted. This is strong when-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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it reveals the tool is a meta-probe that internally calls ai_visibility_check multiple times, and it discloses the return contents (ranked list with score, confidence, signal density). This goes beyond what annotations provide.

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

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

Two sentences, front-loaded with the core purpose ('Compare AI visibility across multiple entities side-by-side'), followed by mechanism, use case, and return format. Every sentence earns its place with 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 moderate complexity (4 parameters, no output schema) and rich annotations, the description covers the essential behavior, return value shape, and example use case. It slightly lacks explicit mention of how models/_apiKey affect probing behavior, but that is covered by the schema. Overall, it is adequately 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 description coverage is 100%, so the baseline is 3. The description does not elaborate on parameters, but the schema already contains detailed descriptions for entities, models, _apiKey, and context, including semantics like 'First entry treated as the subject'. Thus the description adds no additional parameter 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 states a specific verb ('Compare'), a resource ('AI visibility across multiple entities'), and the mechanism ('Probes each entity with ai_visibility_check, ranks by score'). It clearly distinguishes from siblings like ai_visibility_check (single-entity) and compare_entities (generic) by focusing on competitive AI-marketing visibility.

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

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

Provides a clear use case: 'competitive AI-marketing audits' with an example question. It implies this is the batch/competitor-oriented counterpart to ai_visibility_check, but does not explicitly name alternatives or state when not to use it. Thus it has clear context but no exclusions.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavioral details: it fans out to two external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and the sources_failed field reports timeouts. This is comprehensive transparency that aids the agent in setting expectations.

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

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

The description is a single, dense paragraph that front-loads the core purpose and provides all necessary information in a structured flow: purpose, usage, return value, failure behavior, and ecosystem limitations. Every sentence adds value, with no redundant content.

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

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

Given the complexity of the tool (multi-source aggregation) and the absence of an output schema, the description fully enumerates the return fields, failure behavior, and timing expectations. This is more than sufficient for an agent to understand what the tool does and what to expect from its results.

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

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

The input schema already provides 100% coverage for both parameters, including descriptions for 'package' and 'version'. The description adds minimal additional parameter context (e.g., NPM ecosystem only, scoped packages accepted) which mostly mirrors the schema, so it does not significantly elevate the 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?

The description clearly states the tool's purpose as a composite 'should I add this npm package' check, detailing the specific data sources and the types of questions it answers. This distinguishes it from sibling tools like deep_research or validate_claim by focusing on npm dependency evaluation.

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 the tool ('Use whenever an agent asks...') and provides clear exclusions for non-NPM ecosystems, directing to deps.dev:version directly. This gives strong guidance on when to use this tool versus 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 false, covering safety. The description adds meaningful behavioral context: that it returns a synthesized answer and a ranked list with relevance scores, which is beyond the schema. It doesn't discuss rate limits or errors, but this is acceptable given annotation coverage.

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

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

The description is two sentences plus an example, with no wasted words. It front-loads the purpose, then adds usage guidance and a concrete example, all of which earn their 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?

An output schema exists, so the description needn't fully explain return values, yet it still conveys the key output structure (synthesized answer plus ranked sources). Combined with the schema, the overall package is complete for a search tool of this complexity, though it could mention which sibling scenarios it is not suited for.

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 each of the six parameters described, including enums for topic and search_depth. The description provides an example but no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb-resource pair ('AI/LLM-optimized web search') and clearly defines the output: a synthesized natural-language answer plus a ranked list of sourced results with title, URL, snippet, and relevance score. It explicitly distinguishes the tool from scraping a generic search engine, which aligns with its sibling context.

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 to prefer this tool over scraping a generic search engine when grounded, citable web context is needed. It does not contrast with sibling tools like deep_research or search_within, but the alternative it names is actionable and relevant.

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 several behavioral traits beyond the annotations: it returns 'character offsets and similarity scores', uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', and has a '200K chars cap (longer inputs are truncated and flagged)'. These details inform the agent about output format, performance characteristics, and failure modes—valuable context that annotations don't provide. No contradiction with the readOnly/idempotent hints.

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

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

The description is dense but well-structured, with clear front-loading of purpose and usage. Each sentence contributes value: purpose, use case, companion tool, technical details, and limits. It's slightly longer than strictly necessary, but no sentence is wasteful. The structure aids readability and 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 tool with no output schema, the description explains what the agent receives (top-N passages with character offsets and similarity scores) and the operational context (when to use, truncation behavior). It covers the main use case, integration with a sibling tool, and technical constraints. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema already documents all 3 parameters with descriptions (100% coverage), so baseline is 3. The tool description adds illustrative examples for the 'text' parameter (e.g., 'SEC 10-K body, article, long tool result') and clarifies the 'query' parameter with natural-language examples. This goes beyond the schema's generic descriptions, enriching parameter understanding without duplicating it.

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 semantic search inside a fetched record, with a specific verb ('search') and resource ('record/text'). It distinguishes itself from siblings by explicitly noting 'INSIDE a fetched record' and referencing ask_pipeworx_grounded as a companion tool. The purpose is unambiguous and differentiates from broader search 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 states when to use this tool: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also provides an explicit alternative/companion workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear usage context and exclusion.

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 (readOnly=false, idempotent=true, etc.), the description adds significant behavioral detail: the auth requirement and persistence limitation, phone verification and 10/day SMS cap, and the feed delivery mechanism via recent_alerts or a registry URL. This enriches the agent's understanding beyond what annotations alone convey.

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

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

The description is dense but well-organized, front-loading purpose and then covering auth, types, and delivery. Every sentence carries necessary information, and the length is justified by the tool's complexity. It avoids verbosity and remains scannable despite the many details.

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

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

Given the complexity (multiple subscription types, nested delivery options, no output schema), the description covers the core aspects: subscriptions, auth, types, and delivery. However, it omits the webhook delivery channel from the main prose and misses two subscription types (patent_grant, clinical_trial) that are only in the schema. Still, the schema fills these gaps, so the description is nearly complete.

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

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

The input schema already provides 100% coverage of all parameters with detailed descriptions, including the nested delivery object. The description's main text adds readability with concrete examples (e.g., items:["5.02"] = officer change) but does not fundamentally extend the schema's meaning. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe, and even states it returns the new subscription id. This leaves no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool: it requires a Pipeworx OAuth account, notes that anonymous/BYO cannot persist, and explains delivery channels including the always-on feed and optional email/SMS. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use list_subscriptions to view existing'), though this can be inferred from sibling 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: it returns example questions (not answers), draws from a 'live catalog of thousands of tools', and can be scoped by topic. This goes beyond the annotations by explaining the output's nature and dynamic source, with 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?

The description is front-loaded with natural user queries, followed by a precise statement of purpose, output composition, and usage instructions. Although it is relatively long, every sentence contributes essential context for an onboarding tool. The structure flows logically from what the tool does to how to call it, making it efficient for an agent 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?

The description covers all necessary aspects: purpose, input options, output outline (category-bucketed questions with exact tool + argument shape), and its role in learning meta-tools. Without an output schema, this description sufficiently explains what the agent will receive and how to use the results. It is complete for an onboarding tool of this complexity.

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

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

The input schema already fully describes the optional `topic` parameter, including allowed values and the behavior when omitted. The description merely repeats examples like 'finance', 'pharma', 'betting' and the 'no arguments' case, adding no new constraints, semantics, or interaction details beyond what the schema provides. 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 identifies the tool as the onboarding entry point for connected agents, with a specific function: 'Returns category-bucketed example questions ... each with the exact tool + argument shape that answers it.' It also distinguishes itself from siblings by emphasizing that it is the FIRST tool to use when you don't know what Pipeworx can do, and it exists to teach how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes two invocation modes (no arguments for full spread, or topic for focus) and provides examples of valid topic values. This clearly informs when and how to use the tool, and indirectly implies it's not needed when you already know what to ask.

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 that this tool returns 'a synthesized answer plus ranked articles each carrying title, url, publication content, and a relevance score — the full text, not just a headline.' This goes beyond the annotations (which already mark it as readOnly, openWorld, idempotent, non-destructive) by detailing the rich return structure and the availability of full article text for quoting and citing.

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 purpose statement, example queries, return content details, and usage guidance—all in a few sentences. It is front-loaded with the core value proposition. Minor redundancy (e.g., repetition of 'full text' and 'not just a headline') could be trimmed, but overall it is efficient and earns its keep.

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 4 parameters (100% schema coverage) and no output schema, the description covers the return structure, usage context, and parameter defaults adequately. It explicitly mentions the full-text capability, which is critical for an agent that needs to cite sources. The only gap is that it does not explain how the 'synthesized answer' is generated or its format (e.g., summary vs. extractive answer), but this is not a major deficiency given the tool's focus on news retrieval.

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 adds marginal value beyond the schema by providing example queries (e.g., 'Anthropic', 'GLP-1 drug pricing') and noting default values for `days` (7) and `max_results` (5). However, the schema already documents all parameters, and the description does not compensate beyond listing defaults.

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

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

The description explicitly states the tool returns 'Recent NEWS coverage with FULL ARTICLE TEXT' and provides concrete example queries like 'latest news about <company/person/topic>'. It clearly distinguishes the tool as a specialized news-focused search, which is distinct from the general 'search' sibling tool.

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

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

The description gives explicit guidance on when to use this tool: when the question asks 'what is being REPORTED about a specific entity or topic.' It also provides usage conditions such as freshness-windowed via `days`, and contrasts it with other tools by calling it the 'premium news path' with funded key and no shared free-tier quota.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This complements the annotations (e.g., destructiveHint=false) by explaining the non-destructive nature in concrete terms. 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 and front-loaded: two sentences that state the action, key constraints, and side-effect behavior. Every sentence adds value, with no filler or repetition of schema details.

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

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

For a simple one-parameter tool, the description covers the essential aspects: purpose, ownership, and the non-destructive deactivation behavior. It could mention error cases (e.g., nonexistent id) or reversibility, but these are not critical for basic usage. The lack of an output schema is adequately compensated by the behavioral explanation.

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 the parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description's 'by id' adds nothing beyond this. The baseline of 3 is appropriate since the 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 tool's function: 'Cancel a subscription by id.' This uses a specific verb and resource, directly distinguishing it from siblings like 'subscribe' and 'list_subscriptions.' The purpose is unambiguous.

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

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

The description provides clear context for when to use the tool—to cancel a subscription—and explicitly notes a constraint: 'you can only cancel your own subscriptions.' This effectively tells the agent when not to use it (for others' subscriptions), though it doesn't name alternative tools explicitly. The deactivation note also clarifies the side-effect 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?

Goes well beyond annotations by disclosing the verdict enum semantics, warning that could_not_verify is not evidence and carries verification_error{stage,detail}, and explaining the two execution paths (SEC EDGAR + XBRL vs grounded pipeline). This provides important behavioral nuance beyond readOnlyHint and openWorldHint.

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 but still organized, starting with trigger phrases, then usage, routing, output, and caller warnings. Some slight redundancy (e.g., 'natural-language claim verification' appears near the start and is implied elsewhere), but every sentence carries relevant information.

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

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

With no output schema, the description fully covers return semantics by listing the verdict set, citation format, reasoning, and error fields. It also explains edge cases (could_not_verify vs unsupported), the structured fast path, and the efficiency benefit, making it 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?

The input schema already provides rich descriptions for both parameters (claim examples, tolerance_pct semantics with default and override behavior). The tool description itself adds no additional parameter-specific details, so the baseline of 3 applies given the high schema coverage.

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

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

The description clearly states that the tool performs natural-language claim verification against authoritative sources, with specific trigger phrases ("fact check", "verify the claim that…"). It distinguishes the tool from sibling research/search tools by focusing on verifying factual claims and by describing the structured vs grounded pipeline distinction.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic between company-financial claims and all other claims. It does not explicitly name when-not-to-use or list alternative tools, but the contextual guidance is strong enough to infer appropriate use.

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