wikipedia

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

Annotations already declare this as a safe read-only, idempotent operation. The description adds valuable context: the default free Workers AI model, the BYO Anthropic key with direct cost to the user, and the per-model response structure ({score, confidence, signals, raw_response}), which goes beyond annotation metadata.

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

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

Three sentences with the main action up front, followed by key details (default model, cost, return format) and use cases. No filler or redundant phrasing.

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 explicitly states the return shape and covers key usage scenarios. For a simple read-only tool with fully documented params and annotations, this is adequately complete; it could mention the exact models supported or signal semantics, but that's not critical.

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

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

All four parameters are already fully described in the schema (100% coverage), so the baseline is 3. The description adds some cross-parameter context (e.g., '_apiKey' is only needed if 'anthropic' is in the models array) and clarifies cost implications, but it doesn't provide syntax or format details beyond the schema.

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

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

The description uses a specific verb ('Probe') and clearly states the tool's function: querying LLMs about an entity and producing a visibility score (0-100) per model. It distinguishes itself from sibling read/search tools by focusing on AI brand awareness scoring 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?

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which tells the agent when to choose this tool. However, it doesn't name alternative tools or state when not to use it, only the intended scenarios.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful behavior beyond that: it transparently says the tool routes to the right source tool, fills arguments, returns structured data with stable pipeworx:// citations, and works on every tier in one fast call. There is no contradiction with annotations.

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

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

The description is intentionally long but front-loaded with its core purpose and usage triggers, then examples, then escalation paths. It earns most of its length, though some phrases like "PREFER OVER WEB SEARCH" and "START HERE" are repeated and the example list could be slightly 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?

For a complex router tool with no output schema, the description is complete: it explains return value shape (structured answer with citation URIs), performance characteristics (one fast call, all tiers), supported domains, invocation triggers, and alternatives. An agent has enough to decide when to call it and roughly 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% — all six properties are documented as aliases for the single required natural-language `question`. The description reinforces that input is a natural-language question and offers examples, but it adds no new parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description names a specific verb/role — routes the question to the right tool among 5,724 across 1,497 sources, fills arguments, and returns structured answers with citation URIs. It also differentiates from close siblings (ask_pipeworx_grounded, deep_research) by naming exactly when each is the upgrade, so an agent can tell them apart.

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

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

Explicit guidance is everywhere: "PREFER OVER WEB SEARCH", "START HERE for most questions", and a set of trigger phrases like "what is", "look up", "find", "get the latest". It also states when NOT to use it and which sibling to step up to (ask_pipeworx_grounded for hallucination-resistant evidence, deep_research for broad/multi-part fan-out).

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: it is a full working router with no fallback, identical to ask_pipeworx when no candidate is active, and results are compared to the stable router to decide on merges. Annotations already mark it read-only, idempotent, and non-destructive, and the description complements these without contradiction. This is more than enough 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 information-dense and front-loads the core identity and behavior. The parenthetical retirement date and repeated emphasis on 'identical' and 'matches exactly' add slight redundancy, but every sentence contributes useful context. It is concise without being under-specified.

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

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

For a tool with no output schema, it references the same response shape as ask_pipeworx and instructs to use it exactly like the stable sibling, which gives an agent enough to invoke it correctly. Combined with the rich annotations and complete parameter schema, the description is close to complete. A slightly more explicit description of the response format would push it to 5.

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 all six parameters are documented as aliases for the single required 'question' parameter. The description adds no additional parameter details beyond noting 'same arguments' as ask_pipeworx. Since the schema carries the full semantic load, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router covering 5,724 tools with the same arguments and response shape. It distinguishes itself from the stable sibling by noting that candidate routing improvements are enabled live during tests. This goes beyond the name/title and states the tool's function and scope precisely.

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 exactly like ask_pipeworx when you want the newest routing', naming the sibling and giving a concrete selection criterion. It also notes that no candidate is currently active, so behavior matches ask_pipeworx exactly. It could be stronger about when to prefer the stable router over the beta, but the guidance is clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description goes well beyond them by detailing the exact success return shape, the explicit refusal reasons, the fact that answers are extracted only from tool results, and the additional cost. This gives the agent a precise behavioral contract.

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

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

Every sentence earns its place: purpose, routing, extraction rule, return contract, use cases, and cost tradeoff. It is dense but well-organized, with the most important distinguishing detail ('grounded', 'extracts from tool result') presented first.

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 documents return values and refusal reasons. It also addresses the operational context (extra LLM call, when to use vs sibling), making it complete for an agent deciding to call and interpret 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 already covers 100% of parameters, all of which are aliases for the single 'question' string. The description does not add new parameter-specific semantics, but the schema is sufficient on its own, 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 identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific extraction mechanism and refusal behavior. It explicitly distinguishes itself from ask_pipeworx by noting same routing but grounded extraction, which differentiates it from its closest sibling.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also gives a when-not-to-use rule by recommending ask_pipeworx for casual lookups and notes the extra LLM call cost as a tradeoff.

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

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

Even with readOnlyHint/idempotentHint annotations, the description goes far beyond them by disclosing critical behaviors: the resolver contract with confidence levels, low-confidence short-circuiting, closed-market handling, wide-spread illiquidity flags, parent-event extraction, and resolution-rule risk (cancellation/void settlement). This is precisely the contextual richness that annotations alone cannot 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 lengthy but extremely well-structured with clear section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and a front-loaded purpose statement. Each section earns its place given the tool's complexity, though certain details could be condensed without losing essential information.

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

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

In the absence of an output schema, the description comprehensively documents all return shapes: result.market, result.analysis, result.evidence, statuses, parent_event, news fallback fields, and resolution-risk warnings. It also covers safety mechanisms and blocking behaviors, leaving few ambiguities for an AI agent to invoke the tool correctly and interpret results.

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

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

The input schema provides 100% coverage for all three parameters (market, depth, include_raw), including their descriptions and defaults. The description reinforces the `market` parameter's accepted formats (slug/URL/text) but adds no new semantics beyond the schema. Since the schema does the heavy lifting, 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 explicitly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling Polymarket tools (e.g., polymarket_edges, polymarket_arbitrage) by focusing on evidence gathering and market-vs-model comparison. The verb 'Research' and specific resource (Polymarket bet) make the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples for different bet categories, showing when the tool is applicable. However, it does not explicitly compare against sibling tools or state when NOT to use it, leaving a minor gap in 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 declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond that: source data (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. There is no contradiction with annotations.

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

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

The description is dense but front-loaded with trigger phrases and a clear directive. Every sentence contributes unique information—usage triggers, data sources, sorting behavior, and efficiency gains—without redundancy or filler. It is structured to be scannable and immediately actionable.

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 2-parameter schema, strong annotations, and no output schema, the description fully covers what the tool returns (paired data, citation URIs), how results are ordered, and what each type does. It also names the alternative approach it replaces, making its role in the toolset clear. No significant 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?

Although schema coverage is 100%, the description enriches the parameters substantially: it explains what 'type' maps to in terms of data sources, gives concrete examples for 'values' (tickers vs drug names), and clarifies output behavior (sorted by primary metric). This goes well beyond the schema's terse property descriptions.

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

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

The description uses specific verbs ('compare', 'rank', 'side-by-side') with a clear resource ('companies or drugs'), and explicitly differentiates itself from sequential single-entity lookups. It also enumerates concrete query phrasings that trigger the tool's use, making its purpose unmistakable.

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

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

The description provides explicit usage criteria: trigger phrases like 'X vs Y', 'which is bigger', 'rank these companies', and a strong directive to always prefer this over sequential single-pack lookups when comparing entities. It also gives per-type data sources, clarifying when company vs drug comparison 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?

The description adds substantial behavior beyond the annotations: it discloses the findings-packet shape, gap reporting, never-invented evidence, contradiction scanning, semantic excerpting, citation fetchability, and latency expectations. It aligns with the readOnly/idempotent/destructive annotations and adds richer operational 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 long but information-dense, with the account requirement front-loaded and clear routing guidance toward the end. Some clauses are run-on and slightly repetitive, but each major behavior earns its place.

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

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

For a tool with no output schema, the description covers return format, evidence structure, gaps, contradictions, latency, auth requirements, and alternatives. An agent has everything needed to decide when to call it and what to expect.

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 both parameters with 100% coverage, so the baseline is 3. The description adds meaningful depth semantics beyond the schema: what each depth value does, how hops/gap recovery differ, and which depths require payment. It slightly overlaps with schema content but still adds value.

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

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

The description states a specific action and resource: multi-source structured research across Pipeworx's data catalog, explicitly distinguishing itself from open-web search and from the ask_pipeworx siblings. The 'Best for' clause clarifies the exact shape of question it is built for.

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

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

Usage boundaries are explicit: use for broad/multi-part structured-data questions; use ask_pipeworx instead for single lookups and for breaking/current-news topics. It even covers account-tier routing, saying unauthenticated users should use ask_pipeworx.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds value by disclosing return behavior: returns top-N relevant tools with names, descriptions, and full input schemas, ready to call directly with no second lookup. This goes beyond annotations and helps the agent understand the tool's output characteristics.

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 'Find tools' and uses a few sentences to cover purpose, use cases, return value, and strategic advice. While the domain list is somewhat long, it provides useful context and every sentence serves a purpose. It is concise enough for a meta-tool.

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

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

For a discovery tool, the description is complete: it explains what it does, when to use it, what it returns (top-N, with schemas and examples), and even notes the advantage of no second lookup. Given the tool has no output schema, the description adequately covers the return format, making it self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the query concept ('describing the data or task') and mentions 'top-N' which aligns with the limit parameter, but it does not add meaningful detail beyond what the schema already provides. The schema fully documents query and aliases, so the description's contribution is marginal.

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

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

Description clearly states a specific verb+resource: 'Find tools by describing the data or task.' It enumerates multiple domains and explicitly distinguishes itself from other tools by being a meta-tool for discovery. This is distinct from sibling tools like search_wikipedia or search_within, which are not about discovering tool options.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This both states the appropriate context and implies it should not be used when a specific answer is already known.

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 readOnly/openWorld/idempotent/non-destructive; the description adds valuable context: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF, notes the patents API 'soft-fails until reactivated,' and explains the GDELT→GNews 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?

Long but well-structured: examples front-load intent, followed by sources, return list, and input constraints. Every sentence conveys distinct information, though the density makes it slightly less concise than ideal.

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

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

This is a complex multi-source tool with no output schema, so the description must explain return values and caveats. It enumerates all returned fields (cik, filings, fundamentals, patents, news, LEI), notes the sunsetting USPTO API, and clarifies input handling. This is sufficient 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 covers both parameters 100%, including type enum and value format. The description mostly repeats 'ticker or zero-padded CIK' and 'names not supported,' adding examples but no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

Description opens with concrete user phrasings and states it provides a 'full cross-source profile of a US public company in ONE parallel call.' The verb 'profile' plus resource 'US public company' is specific and distinct from siblings like resolve_entity 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?

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name).'

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

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

The destructive nature is already declared via annotations (destructiveHint: true, idempotentHint: true). The description adds 'previously stored' and 'the agent saved earlier' as context, but does not go beyond annotations with detailed behavioral traits like irreversible deletion or handling of missing keys. It is adequate but not rich.

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

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

The description is three sentences, each earning its place: purpose, usage scenarios, and sibling tool pairing. No redundancy or wasted words.

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

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

For a simple single-parameter tool with comprehensive annotations and schema, the description fully covers what the tool does, when to use it, and related tools. No output schema is needed for this straightforward operation.

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

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

Schema description coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, 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 action ('Delete'), the resource ('previously stored memory'), and the mechanism ('by key'). It distinguishes itself from siblings like 'remember' and 'recall' by explicitly pairing with them and focusing on deletion of stored 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 provides explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and names complementary tools ('Pair with remember and recall'), giving clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful process details ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output format ('single text blob ready to drop at site-root/llms.txt'), which goes beyond the annotations and helps users understand actual behavior.

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

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

The description is concise and well-structured: it front-loads the main purpose, briefly explains the process, states the output format, and lists use cases. Every sentence earns its place with zero unnecessary verbosity.

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

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

The tool has only 2 parameters, no output schema, and rich annotations. The description effectively covers purpose, process, output, and use cases. It might lack error-handling or limitation details, but for a simple read-only tool with strong annotations, it is sufficiently 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 both parameters (url and max_links) are already fully described. The description adds minimal extra semantics beyond saying 'any URL' and mentioning site-root, but it doesn't elaborate on max_links or any new parameter details, meriting the baseline 3.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL so AI crawlers (ChatGPT, Claude, Perplexity) can index the site cleanly.' This uses a specific verb (generate) and resource (llms.txt file), and the process details (fetch, extract, emit) distinguish it from siblings like ai_visibility_check.

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

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

Provides explicit use cases via 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or exclusions relative to similar tools like scan_competitor_ai_presence.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive hints, so the bar is for added context. The description contributes exact-match failure behavior ('on a miss you get a user_error naming search_wikipedia as the recovery'), truncation by max_chars, and — critically, since there is no output schema — the exact return format (plain text, '== headings ==' markers, table rows one per line with | separators). This goes well beyond what annotations 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 verb and core distinction are front-loaded in the first sentence, and the body follows a logical structure: use cases → answer types → direct-call strategy → miss handling → alternative routing → parameter interplay → output format. It is long and slightly repetitive in places (the question-phrasing list and title-pattern examples overlap with earlier use cases), so it is not maximally lean, but every sentence does carry routing or formatting value.

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

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

There is no output schema, so the description must cover return semantics by itself — and it does: plain text, heading markers, table cell separators, max_chars capping, and exact-match failure behavior. Combined with schema documentation for all three params and annotations for the safety profile, nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents title, section, and max_chars with ranges and defaults. The description adds marginal value for parameters: restating the section/max_chars interplay ('Omit section for the whole article (capped by max_chars); pass a section number...') and giving concrete title-pattern examples, but those largely mirror or barely extend the schema. Baseline 3 is appropriate; no extra meaning is truly necessary at 100% 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 opens with a concrete verb+resource: 'Full text of a Wikipedia article by title — the ACTUAL prose AND its tables, not just the lead paragraph.' It explicitly distinguishes itself from get_article_summary (lead paragraph only) in the first sentence, and later names the miss behavior for searches. An agent can tell exactly what this tool returns and how it differs from close siblings.

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

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

Gives explicit when-to-use and when-not-to-use guidance: 'CALL IT DIRECTLY when the title is predictable from the question', 'constructing the title and reading the article beats searching first', 'PREFER OVER get_article_summary whenever the lead paragraph is not enough', and names search_wikipedia as the recovery path on a miss. It even states the condition for using sections from get_article_sections — nothing is left to inference.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds concrete behavioral context: 'Cheap, structural-only' and clarifies that it returns headings without prose, which is useful beyond the structured fields. 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?

Front-loaded with the core purpose in the first clause, then follows with targeted usage guidance, chaining recommendation, and a performance note. Every sentence earns its place—minimal and efficient.

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

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

Given the single-parameter schema, rich annotations, and presence of an output schema, the description covers purpose, usage, performance, and chaining. It is appropriately complete for a simple, structural-only tool without over-explaining.

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 a clear explanation and example for the title parameter. Description only restates 'by title', adding no meaning beyond the schema, 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?

States a specific verb+resource: returns the section outline/table-of-contents of a Wikipedia article. Clearly distinguishes from siblings with 'without the prose' and references get_article_summary for lead text, establishing a unique scope.

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

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

Explicit when-to-use: long articles needing navigation to a specific section, directly contrasting with 'entire summary'. Names get_article_summary as a chaining alternative. However, it does not specify when not to use or mention other siblings like get_article_extract, making guidance clear but not exhaustive.

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 the safety profile. The description adds valuable behavioral context beyond annotations: it emphasizes 'exact title' matching, notes performance characteristics ('faster + cheaper'), and explicitly lists the returned content. This goes beyond what annotations alone provide, though it doesn't describe error handling for missing titles.

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

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

The description is three sentences, each earning its place: first states the function and performance, second lists return items, third provides usage context and a pointer to an alternative. There is zero 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?

For a simple, one-parameter read-only tool with a rich output schema and strong annotations, the description covers what the tool does, returns, when to use it, and how it compares to alternatives. No additional context seems necessary for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% for the title parameter, so the baseline is 3. The description adds semantic nuance by emphasizing 'exact title' and 'canonical title,' clarifying the precision required. It also contextualizes the title's role in getting a 'standard prose answer.' This extra guidance justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'AUTHORITATIVE summary of a Wikipedia article by exact title' and enumerates the return values: 'lead paragraph, one-line description, thumbnail image, and a few related-content links.' It also distinguishes it from sibling tools like get_article_sections, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you already have the canonical title (got it from search_wikipedia, or it's a well-known entity) and need the standard 'what is X' prose answer.' It also names alternatives and exclusions: 'typically faster + cheaper than search_wikipedia + get_article_sections + scrape' and 'For the full section breakdown use get_article_sections.' This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about the random behavior and return structure (title, introduction text, page ID), which goes beyond what annotations provide. It does not contradict any 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 exactly two sentences, front-loaded with the primary purpose and followed by the return value. Every word 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?

For a tool with one optional parameter, complete annotations, and an output schema, this description is sufficient. It communicates the essential purpose, expected output, and random nature, leaving no critical gaps for the agent to make an informed invocation decision.

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 single parameter 'count' has a complete description in the input schema ('Number of random articles to fetch (1-10, default 5)'), so the description need not repeat it. The tool description itself does not elaborate on parameter semantics, but with 100% schema coverage, this is acceptable per the baseline.

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

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

The description clearly states the tool's function: 'Discover random Wikipedia articles for serendipitous learning.' The verb 'Discover' combined with 'random' and 'serendipitous' distinguishes it from sibling tools like search_wikipedia or get_article_extract, which target specific articles. It also states the return payload (title, introduction, page ID).

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

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

The description implies use for exploratory discovery ('serendipitous learning') but does not explicitly contrast with alternatives like search_wikipedia or get_article_summary. There is no 'when not to use' guidance or mention of sibling tools, so usage context is only 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 convey readOnlyHint and destructiveHint, so the safety profile is covered. The description adds value by detailing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the caller-specific scope, enhancing transparency beyond the structured data.

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

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

Three sentences: purpose, return fields, and usage guidance. Information is front-loaded and each sentence serves a distinct purpose 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?

The tool is simple (one optional parameter, no output schema) and the description provides sufficient context: what is returned, the scope ('caller's'), and typical use cases. Combined with strong annotations, there are no significant gaps for an agent to mis-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?

The single optional parameter include_inactive is fully described in the schema with 100% coverage. The tool description does not add additional meaning about the parameter, so it relies on the schema, which is acceptable per the baseline.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb ('List') and resource ('subscriptions'). It distinguishes itself from sibling mutation tools like subscribe and unsubscribe by focusing on read-only listing.

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 suggests when to use the tool: to review current monitoring before adding more subscriptions or to find a subscription id to cancel. While it doesn't name specific alternative tools, the context is clear enough for an agent to decide between this list operation and mutation operations.

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?

Despite sparse annotations, the description fully discloses behavior: rate limiting ('Rate-limited to 5 per identifier per day'), quota ('doesn't count against your tool-call quota'), the claim_token workflow, and feedback handling ('team reads digests daily'). This goes well beyond annotation hints and provides all necessary operational 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 detailed but well-structured, with clear sections for usage, exclusions, workflow, and limits. Sentences are purposeful and front-loaded with the core purpose. While slightly long, each sentence earns its place and the structure aids 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?

Given no output schema, the description fully explains return behavior (claim_token) and how to use it for follow-up. It covers rate limits, quota, and alternative channels. It is complete for a feedback tool with 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and message specifics ('Be specific... 1-2 sentences typical'). This exceeds 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than asking questions.

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

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

Provides explicit when-to-use guidance: '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).' Also gives a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds value by disclosing the aggregation source ('derived from CF analytics-engine'), privacy (no PII), and caching behavior ('Cached 5min-1h depending on window'). It also clarifies the data shape (pack, tool, count). This goes beyond the basic safety profile.

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 and front-loaded with the main purpose. The numbered use cases make it scannable, and each sentence adds substantive value. It is slightly longer than necessary, but no information is redundant or wasted.

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 compensates by stating what is returned (top tools, top packs, total call volume) and the data format (pack, tool, count). It also covers caching and privacy aspects. For a simple read-only tool with one optional parameter, this is sufficiently 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 schema already covers 100% of the parameter with a good description of window semantics (shorter=hot, longer=steady-state). The description adds extra nuance about caching ('Cached 5min-1h depending on window') that informs window selection, plus the use cases imply which window to choose. This exceeds the baseline for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It effectively differentiates from siblings like discover_tools by emphasizing 'what other AI agents are calling on Pipeworx right now,' making it uniquely about trending usage rather than tool discovery.

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 use cases: (1) discovering hot data sources, (2) confirming canonical choice, (3) checking alignment with agent needs. These give concrete guidance on when to use the tool. However, it does not name alternative sibling tools or explicitly state when not to use it, slightly limiting the differentiation.

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 far beyond the readOnly/idempotent annotations by explaining internal checks (Jaccard ≥0.30, partition placeholder filter >20%), the fill-check behavior ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade'), and edge-case outputs like skipped_low_similarity. This is exactly the behavioral context annotations don't 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 long and dense, but every section earns its place with labeled concepts (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It could be more scannable with bullet points, but the structure is logical and front-loaded with the core purpose.

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

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

For a complex tool with no output schema, the description covers all critical aspects: modes, inputs, internal logic, response fields (opportunities[], partition_check), fill-check behavior, and related tools. It even explains how to interpret null signals and placeholder filtering, ensuring the agent knows what to expect.

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 both parameters described, so baseline is 3. The description adds deeper semantic value by explaining what each parameter triggers (e.g., 'walks child markets, checks date-axis/threshold-axis ordering' for event) and provides concrete example slugs like 'fed-decision-may-2026', which goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the method, and further distinguishes three operation modes (no-args, event, topic), making its scope unmistakable and differentiating it from siblings like polymarket_edges.

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

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

The description gives explicit when-to-use guidance: 'event (recommended for a specific market)', 'topic (for cross-event scanning)', and 'Call with NO args for a trending_scan'. It also directs users to 'polymarket_fill_risk' for custom sizing, providing clear alternatives and 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 annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral traits: 1-hour KV caching keyed on knobs, placeholder-slug filters, partition overround mechanics, funnel diagnostics in _diagnostics, Fed bets exclusion from ranking, and a 24h-move warning when the edge may already be priced in. It also explains why segments can be empty via diagnostic counters. This goes far 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?

The description is dense and information-rich, with clear section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. However, it is quite long and packs many details (e.g., per-sport alpha values, specific gate thresholds) that may be more appropriately placed in the output schema or documentation. It earns its place technically but sacrifices conciseness.

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

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

Even without an output schema, the description comprehensively details the response structure: 'RESPONSE TOP-LEVEL: by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note... and _diagnostics{...}' It also explains what each opportunity includes (edge_pp_net, kelly_fraction, etc.) and the caching behavior. For a complex tool with 9 parameters and no output schema, this description fills the gap nearly completely.

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 parameters have descriptions), so the baseline is 3. The description adds semantic context by explaining how the knobs interact: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also clarifies a subtle behavior: partition arbs always return kelly_fraction_half=0 at the parent level, so min_kelly doesn't filter them but min_partition_leg_kelly does. This adds value beyond the schema.

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

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

The description opens with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the tool's intended use ('what should I bet on today') and differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreements and the three model-family segments.

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 strong contextual guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains when the tool is appropriate and how knobs like min_liquidity/max_spread_pp gate tradeability. However, it doesn't explicitly state when NOT to use it or name direct alternatives (e.g., polymarket_arbitrage for pure arbitrage), so it stops short of full when/when-not clarity.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals significant behavioral details: snapshots are written on cache-miss so gaps mean no scan; history is bounded by 60-day TTL; decay computed from daily closes not intraday; and the response structure including expired opportunities and snapshot_dates. This goes well 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?

The description is dense but well-structured, with distinct sections for purpose, args, response, and limits. Every sentence provides useful information, though it is quite long for a two-param tool. It is front-loaded with purpose and organized, but not as lean as it could be.

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

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

Given no output schema, the description completely explains the return shape (tracked[], expired[], snapshot_dates[]) with field-level detail. It also covers limitations (TTL, snapshot start, daily closes) and the behavioral quirk of snapshot gaps. This is comprehensive for a complex time-series 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 fully describes both parameters (days with default/clamp, window with enum values). The description repeats this information in the Args section without adding meaningfully new details. Since schema coverage is 100%, a baseline of 3 is appropriate; there is no added value like parameter interactions or format specifics.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the explicit question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence and decay, not just current edges.

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

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

The description provides clear context for when this tool is appropriate: comparing fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or exclusions, but the focus on persistence/decay makes the use case clear. It lacks an explicit 'use this instead of X' statement, so it does not earn 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?

The description discloses behavior far beyond the annotations: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that partial basket fills convert an arb into an unhedged directional position—critical risk context. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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 extremely dense; every sentence carries actionable detail. It is front-loaded with the core purpose and then structured by mode. Slightly verbose, but the complexity of two modes and risk guidance justifies the length.

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

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

Given no output schema, the description enumerates return values for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs[], etc.), covers all four parameters with mode-specific meaning, and includes practical risk warnings. It is fully self-contained 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?

Though the schema has 100% coverage, the description adds substantial semantics: explains how size_usd is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional, shares per leg), defines the default side logic in basket mode, and mentions clamping. This is meaningful addition over the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal detection or theoretical edge.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also contrasts single-market vs basket modes, giving clear context for choosing between 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description goes far beyond them. It discloses that compatibility warnings can be non-empty even when pairs are returned, that pairing is always unverified, that unknown legs are never paired, that temporal_alignment null does NOT mean aligned, and that spreads are gross of Kalshi fees. No contradiction with 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 long, but it is well-structured with visible section labels (RESPONSE, SAFETY FIELDS, Codes) and front-loads purpose and modes before caveats. Every sentence earns its place given the tool's complexity and the absence of an output schema, though it could still be tightened in places.

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 carries the burden of explaining the response: leg-by-leg prices, matched spread, top_spreads_pp, per-entry flags, skipped counters, fees note, and temporal alignment semantics. It also explains the meaning of each compatibility code and how nulls should be interpreted. This is exceptionally 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?

Schema coverage is 100% — each parameter has a description, examples, and override notes. The tool description adds mode-level semantics: how topic shortcuts auto-fetch events, how explicit parameters override the topic-mapped side, and that both modes run the identical matcher. This is useful context beyond the schema, but the schema already carries most of the parameter meaning.

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

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

The opening sentence states the exact purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The description elaborates with two concrete modes and clearly distinguishes this from the sibling Polymarket-only tools by emphasizing it compares two venues, not one.

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

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

The description explicitly explains when to use each mode: topic for 10 pre-mapped shortcuts, explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics return compatibility_warning today and that 'pre-mapped ≠ tradeable', which is strong cautionary guidance. It does not explicitly name or contrast sibling tools like polymarket_edges or polymarket_arbitrage, so it falls just short of a 5.

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

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

Annotations already convey read-only and non-destructive behavior. The description adds valuable behavioral context beyond annotations by explaining the scoping mechanism (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (retrieve vs. list). This is useful for an agent to understand the tool's operational boundary, though it could go further with details about missing-key behavior.

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

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

The description is two sentences long, front-loaded with the primary action, and includes concrete examples and necessary caveats (scoping). It avoids redundancy with the schema and annotations, earning its length. No filler or unnecessary detail.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers the functionality: both retrieval and listing modes, the source of saved values (via remember), and scoping context. It is complete enough for an agent to use the tool correctly without additional information.

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

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

The input schema already provides 100% coverage of the single optional parameter 'key' with a clear description ('omit to list all keys'). The tool description repeats this behavior but does not add significant new meaning beyond the schema. Thus the baseline of 3 applies, as the description doesn't compensate further.

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: retrieve a value saved via remember, or list all saved keys when key is omitted. It distinguishes itself from sibling tools (remember and forget) by explicitly positioning itself as the retrieval counterpart, and the verb 'retrieve' is specific and action-oriented.

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 usage context, such as 'look up context the agent stored earlier' and concrete examples (ticker, address, research notes). It also gives indirect guidance about when to use it versus alternatives by mentioning 'pair with remember to save, forget to delete,' though it doesn't explicitly state exclusions or 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?

Despite the readOnlyHint annotation, the description transparently discloses that mark_read:true causes a side effect (flags events read, affecting subsequent calls). It also explains the persisted feed and polling behavior, adding material context beyond the annotations. This is not a contradiction because the primary operation is read-only and the side effect is clearly flagged as optional.

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

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

Four concise sentences, each earning its place: purpose, return format, filtering flags, and polling/alternate access. Front-loaded and free of fluff.

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

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

For a read-oriented tool with five optional parameters and no output schema, the description covers return fields, filtering, read-state management, polling suitability, and an alternative access method. It provides sufficient context to invoke correctly without missing critical details.

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

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

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by giving a concrete example for type ('sec_8k'), clarifying the consequence of mark_read ('so the next call only shows newer ones'), and reinforcing that since accepts ISO timestamps. This extra semantic layer justifies a 4.

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 clear verb and resource: 'Pull fired events from your subscription feed.' It distinguishes itself from sibling tools by focusing on subscription alerts, the persisted feed, and its own retrieval semantics. The return fields (source, citation_uri, raw payload) further solidify the purpose.

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

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

Context is clear: the tool is for retrieving recent alerts and supports polling ('Polls work fine'). It mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools. The absence of exclusions or a direct 'when-not-to-use' keeps it from a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant operational detail: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return structure. This goes well beyond annotations and sets correct 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?

Dense but efficient: starts with query examples, then states the core function, lists sources, and closes with an alternative. No fluff; every sentence adds essential information.

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

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

For a tool with no output schema, the description fully covers the return shape (changes[] grouped by source, total_changes, citation URIs), the supported time windows, the fallback behavior, and the limitation (patents soft-fail). This is a complete operational picture for a complex aggregation tool.

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

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

Schema covers all three parameters at 100%, so baseline is 3. The description adds value by explaining `since` formats ('ISO date' or 'relative shorthand') with examples and recommending '30d' or '1m' for typical monitoring. This extra guidance justifies a 4.

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

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

Clear verb ('change feed') and resource ('company'), with concrete example queries that illustrate the intent. Explicitly distinguishes itself from entity_profile, which covers static profiles.

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

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

Provides explicit 'when to use' via example natural-language queries, and an explicit alternative ('Use entity_profile instead when you want the static profile...'). Also explains fallback behavior and window syntax, giving clear context 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?

Annotations already mark this as non-read-only and idempotent. The description adds context about key-value scoping by identifier, 24-hour retention for anonymous sessions, persistent memory for authenticated users, and the ability to delete via forget. 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 five sentences, all purposeful, with the first sentence front-loading the purpose. It includes examples and persistence details, but each clause earns its place 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?

For a simple key-value write with two fully described parameters, the description covers discovery triggers, retention policy, and lifecycle pairing. No output schema exists, but return value is not critical for deciding when to use this tool.

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

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

The input schema covers both key and value with examples at 100% coverage, so the baseline of 3 applies. The description repeats the key-value concept but does not add new parameter-level detail 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 opens with 'Save data the agent will need to reuse later,' clearly stating a specific verb and resource. It also distinguishes the tool from siblings recall and forget by explicitly pairing with them for retrieval and deletion.

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 states 'Use when you discover something worth carrying forward' and explains the benefit of avoiding future lookups. It also names recall and forget as complementary tools and clarifies persistence differences for authenticated vs anonymous sessions.

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 richly discloses behavior beyond the annotations: it explains cascading internal lookups, graceful degradation when LEI/FIGI enrichment is unavailable, ambiguity handling via figi_candidates, explicit unresolved identifiers, and source-labelled results. This goes well beyond the readOnly/openWorld/idempotent annotations.

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

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

The description is front-loaded with purpose and user-phrase examples, then organized by entity type. It is longer than strictly necessary and uses dense parentheticals, but most details are relevant to correct invocation, so it earns a high but not maximal score.

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

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

For a tool with no output schema, the description is unusually complete: it covers input normalization, supported types, failure modes, edge cases, enrichment degradation, and what the caller should expect in ambiguous or unresolved situations. Nothing essential for correct invocation 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?

Even though schema coverage is 100%, the description adds significant meaning for the value parameter: examples (AAPL, CIK, ISIN), the instruction to pass only the entity name, and a concrete bond-issuer example warning that trailing security-class words will fail. This clarifies semantics far 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 purpose: resolving a user-spoken name to canonical/official identifiers that other tools require. It also differentiates itself by noting 'Use FIRST whenever you have a name but need an ID,' which distinguishes its role from sibling tools like entity_profile and compare_entities.

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

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

The description gives clear usage context: 'Use FIRST whenever you have a name but need an ID' and enumerates supported entity types. However, it does not explicitly state when not to use the tool or name alternative siblings, so the guidance is strong but lacks exclusionary clarity.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral details: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. It also reveals the 'first entry as subject' convention. 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?

Three sentences, front-loaded with purpose, then process, then usage context and return format. Every sentence contributes value with no repetition 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?

No output schema exists, so the description compensates by explaining the return structure (ranked list with score, confidence, signal density). It covers the multi-entity comparison process and the optional API key for Anthropic models, though it does not detail error behavior or rate limits, which are less critical for a read-only, idempotent tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for the 'entities' parameter by specifying the first entry is the subject and the rest are competitors. This goes beyond the schema's basic 'array of entities' description, providing narrative context that affects how the tool interprets input.

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

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

The description states a specific verb (Compare) and resource (AI visibility across multiple entities side-by-side), and clearly distinguishes from siblings by explaining it probes with ai_visibility_check and ranks results. This differentiates it from the single-entity ai_visibility_check tool and generic compare_entities.

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

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

Provides clear context for when to use it (competitive AI-marketing audits) with a concrete example query. It does not explicitly name alternatives or when not to use it, but the 'side-by-side' comparison and mention of the underlying probe make the intended use 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?

Beyond the readOnly/idempotent annotations, the description discloses important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This adds significant operational 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 information-dense yet well-structured: it opens with the tool's core purpose, then usage guidance, followed by a compact list of return fields, ecosystem scope, and failure behavior. Every sentence contributes value, and the length is justified by the composite nature of the tool.

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

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

With no output schema, the description compensates by listing the exact fields in the summary block, mentioning per-advisory details and links, and clarifying the partial failure behavior. It covers the full scope of what an agent needs to know about invoking and interpreting 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 full descriptions for both `package` and `version`, including scoped package acceptance and default behavior. The description does not add extra parameter semantics beyond the schema, 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 clearly identifies this as a composite check for adding npm packages, specifying the exact data sources (deps.dev and bundlephobia) and the types of information gathered (license, advisories, bundle size, etc.). It distinguishes itself from sibling tools by scoping to the npm ecosystem and explicitly mentioning what the tool does in one call.

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 triggers ('is X safe / popular / small' or 'what does adding lodash cost me') and offers a clear alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This tells the agent both when to use this tool and when not to.

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

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

The annotations already declare the tool read-only, non-destructive, idempotent, and open-world. The description adds value beyond those annotations: it discloses that results are a single truncated line, that the search covers ~7M continuously updated English Wikipedia articles, and that direct chaining with get_article_extract is required for full content. This is a meaningful behavioral disclosure without contradicting the annotation set.

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?

It is a long description but every sentence adds useful context: exact examples, routing conditions, types of search results returned, chaining behavior, and a comparison to web scraping. The main purpose is front-loaded, and even the longer portions use concrete examples ('Table tennis at the 2026 Asian Games', 'current cabinet members of Japan'). No wasted sentences.

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 explains what is returned, when to use the tool, how to combine it with get_article_extract, and even mentions the scale and update cadence of the corpus. The output schema is already present, so the description needn't enumerate every return field. For the complexity of the tool and the sibling set, this is as complete as one can expect.

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

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

Schema coverage is 100%: the input schema already describes both 'query' and 'limit', including ranges and a well-known English-language restriction. The description adds no new parameter-specific detail aside from implying the query is for Wikipedia search. At 100% 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 description states a clear verb and resource pair ('Search Wikipedia for encyclopedic facts') and enumerates a broad but specific set of use cases (sports schedules, medals, cabinet rosters, biographies). It also differentiates itself from get_article_extract by explicitly saying when the article title is predictable, you should skip directly to get_article_extract.

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 highly explicit routing: use this tool 'when the article title is NOT predictable', and when the title IS predictable, 'skip straight to get_article_extract'. It also names a dedicated domain (government composition and officeholder rosters) and mentions it should be chained with get_article_extract for full content. No ambiguity about which tool to pick.

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 key behaviors beyond annotations: truncation at 200K chars (with a flag), overlapping 500-char windows, BGE-base-en embeddings with cosine similarity, and that every passage includes an offset for verifiability. This adds significant context to 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 detailed but every sentence adds value: purpose, use case, truncation behavior, algorithm, and pairing with a sibling tool. It is front-loaded with the core action and efficiently structured with semicolons and examples, earning its length.

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

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

Given there is no output schema, the description adequately covers return values (passages with character offsets and similarity scores). It also explains the technical specifics (window size, embedding model, truncation) and provides a clear use case, making the tool fully understandable for an AI agent without further information.

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

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

Schema description coverage is 100% for all three parameters, so the baseline is 3. The description adds minor context (e.g., 'text you already pulled' as a usage nuance, 'top-N passages' reinforcing the limit parameter), but does not materially extend the parameter meanings provided by 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: semantic search inside a previously fetched text, returning top-N passages with offsets and scores. It distinguishes itself from siblings like search_wikipedia (external search) and ask_pipeworx_grounded (grounded QA) by emphasizing it operates on a passed-in text.

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 usage guidance is provided: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool ('Pairs with ask_pipeworx_grounded') and explains the workflow: fetch with the gateway, then ground over passages. This directly informs when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable behavioral context: the OAuth requirement, the return of a subscription id, SMS phone verification, and the 10/day cap. It also details webhook signing and auto-disable behavior, which is not trivial. No contradiction with annotations exists.

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

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

The description is dense but well-structured, with clear sections for types and delivery. Each sentence serves a purpose: purpose, auth, supported types, delivery. It could be slightly more scannable, but it avoids fluff and is front-loaded with the core purpose.

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

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

For a complex tool with nested objects and no output schema, the description is exceptionally complete. It covers all supported types, delivery channels, authentication prerequisites, the return value, and even edge cases like webhook signing secret and auto-disable after 10 failures. The agent has enough to invoke correctly without guessing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant meaning by providing concrete examples for each type: sec_8k items code meaning ('5.02' = officer change), polymarket_edge topic example ('fed'), fred_series via series_id, and delivery semantics like verified phone and 10/day cap. This goes beyond the schema's generic descriptions.

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

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

The description uses a specific verb 'Create' with a clear resource: 'proactive monitoring subscription to a live-data event stream.' It also distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by clearly stating its unique function. The return value ('subscription id') further clarifies the action.

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 states a critical prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also explains delivery channels and how to consume the feed via recent_alerts or GET alerts.json, effectively distinguishing when to use this tool versus the feed. However, it lacks an explicit 'when not to use' or direct comparison to sibling tools like list_subscriptions.

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, open-world. Description adds that results are 'drawn from the live catalog of thousands of tools', implying dynamic output, and explains it returns suggestions with exact tool call shapes. No contradictions with annotations.

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

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

The description is front-loaded with user query examples and then explains output, parameters, and usage. It is a single dense paragraph but each sentence contributes useful information; could be slightly trimmed but remains structured and readable.

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

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

For a simple read-only tool with no output schema, the description fully explains what it returns (category-bucketed questions with exact tool + argument shape), the optional topic parameter, and the intended use case. It even mentions the live catalog and categories covered.

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 description already fully documents the 'topic' parameter with allowed values and omission behavior. The description merely repeats examples ('finance', 'pharma', 'betting') and 'topic' usage without adding new semantic detail; hence baseline 3.

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

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

The description clearly states the tool helps an agent discover what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shape. It distinguishes itself from sibling meta-tools like ask_pipeworx and discover_tools by positioning itself as the FIRST onboarding entry point.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides clear guidance on when to invoke and even suggests parameter usage (call with no arguments for full spread, or pass topic to focus).

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

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

Discloses critical behavior beyond annotations: ownership enforcement, deactivation instead of deletion, and impact on historical events via recent_alerts. Aligns with destructiveHint=false and idempotentHint=true without contradiction.

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

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

Two concise sentences, front-loaded with the action, and every clause adds value. No wasted words.

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

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

For a simple one-parameter tool, the description fully covers purpose, constraints, side effects, and relationship to recent_alerts. Output schema not needed; context signals confirm low complexity and full parameter coverage.

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

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

Schema coverage is 100%, so the description adds little beyond the schema. It reinforces that id is the subscription id but does not provide new semantic details beyond what the schema already 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?

Clear specific verb 'cancel' and resource 'subscription'. Distinguishes from siblings subscribe and list_subscriptions by stating the action and object. Ownership enforcement adds precision.

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?

Clear context: use to cancel a subscription. The ownership constraint ('only cancel your own') is an important usage rule. Does not explicitly mention alternatives or when not to use, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond by detailing the return verdicts, the fast path for company-financial claims, the fallthrough to a grounded pipeline, and the crucial semantic distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found). It also warns callers not to treat 'could_not_verify' as evidence, which is critical behavioral context.

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

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

The description is long but highly structured: trigger phrases, use case, sub-path explanations, return values, and an 'IMPORTANT' callout. While slightly verbose, every sentence carries meaningful information and the critical warnings justify the length. It could be tightened, but the organization makes it easy to parse.

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

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

With no output schema, the description compensates fully by explaining the set of possible verdicts, the return of a grounded/structured value with a citation, reasoning, and error semantics. It also covers the two verification routes and the confidence/edge cases. For a tool with two parameters and no 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?

The schema already fully describes both parameters (100% coverage), but the description adds substantial value: it clarifies the tolerance_pct default ('implied by wording, capped at 5'), shows an example override for hallucination detection, and helps the agent decide when to set it. The claim parameter is illustrated with realistic examples, exceeding what the schema alone 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 explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by noting it 'Replaces 4–6 sequential calls' and describes two distinct verification paths with exact detail, making the tool's scope and 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?

Directly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further gives guidance on claiming company-financial vs. other claims and explains the meaning of 'could_not_verify' versus 'unsupported', including that the former must not be shown as evidence. This is explicit, actionable usage direction.

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