Currents

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals cost implications (free vs BYO key), the return format (per-model score/confidence/signals/raw_response + combined view), and model selection behavior. No contradictions with annotations.

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

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

Two efficient sentences convey purpose, usage, cost, and output structure. 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?

The description covers the tool's behavior, input parameters, cost model, and output structure comprehensively given no output schema. For a moderate-complexity tool with 4 params, this is complete.

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

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

Schema coverage is 100% with adequate descriptions. The description adds context: default model, why _apiKey is needed, how context disambiguates. This adds value beyond the schema.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility (0-100) per model. It distinguishes from sibling tools by focusing on AI visibility audits 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 provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to provide _apiKey for Anthropic vs default free model, but doesn't explicitly state when not to use it.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that the tool internally routes to other tools, fills arguments, and returns structured answers with stable citation URIs. It also describes coverage scope (5,798 tools, 1,517 verified sources) and gives concrete input examples, making the behavior of the tool transparent without relying solely on structured 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?

The description is front-loaded with the most important guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It then moves through mechanism, usage triggers, examples, and exclusions in a logical order, with no wasted sentences. The length is justified by the tool's broad routing role and the need to distinguish it from important alternatives.

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 router tool with no output schema, the description still explains what the caller receives: a structured answer with stable pipeworx:// citation URIs. It covers scope, use cases, alternatives, breaking-news behavior, and concrete examples. There is no critical missing information an agent would need to decide whether to invoke this tool or how to phrase the question.

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

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

The input schema already covers 100% of parameters, including the main `question` parameter and five aliases for it. The description does not add new parameter-level meaning, but it does provide example questions that illustrate the expected natural-language form. With full schema coverage, the baseline of 3 is appropriate; the description's examples add marginal value but no semantic 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 clearly states that the tool routes a natural-language question to the right one of 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly positioning itself as the default router. This is a specific verb, resource, and mechanism, not a vague restatement of the name.

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

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

The description is explicit about when to use this tool: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with a concrete list of trigger phrases and example queries. It also names exclusions and alternatives: ask_pipeworx_grounded for high-stakes hallucination-sensitive questions, and deep_research for broad multi-part queries. This gives an agent clear decision criteria rather than leaving usage 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?

Beyond the rich annotations (readOnly/openWorld/idempotent, non-destructive), the description discloses the live-testing behavior: candidate routing improvements are enabled live during tests, the last candidate was retired on 2026-07-26, so behavior currently matches ask_pipeworx exactly. It also explicitly states it 'falls back to nothing' — a full working router, preventing an agent from treating it as a degraded stub. 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?

Four dense sentences with the core identity front-loaded (beta of ask_pipeworx, identical behavior). The length is justified because the tool's situational nuance — live candidate testing, current no-op state, fallback behavior — genuinely requires explanation. Every sentence earns its place; slightly verbose but not padded.

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

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

Complete for a router whose semantics are explicitly delegated to ask_pipeworx: response shape is covered by referencing the sibling, annotations cover the safety profile, and the description covers the beta-specific behavior, current state, and usage. With no output schema, the deferred reference to ask_pipeworx's response shape is an acceptable shorthand, though a brief note on failure behavior would fully close the loop.

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

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

Schema coverage is 100%: all six parameters are documented in the schema, with the five aliases (q, text, input, query, prompt) labeled as aliases for question, and question's description listing all accepted aliases. The tool description adds no parameter-level detail beyond the schema, so baseline 3 is appropriate; the schema carries the full burden and does so adequately.

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 pinpoints an exact verb+resource: a universal router that answers questions by dispatching to the same 5,798 tools as ask_pipeworx, with identical arguments and response shape. It clearly differentiates itself from siblings by framing itself as the experimental/beta edge of the router family, distinct from stable ask_pipeworx and grounded ask_pipeworx_grounded.

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 it exactly like ask_pipeworx when you want the newest routing." It also clarifies the current operational state (no candidate active, matches stable exactly), which directly informs whether behavior differs. It doesn't explicitly name the exclusion case (choose stable ask_pipeworx when you need guaranteed stable routing), but the beta/stable framing makes it inferable.

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 (readOnly, openWorld, idempotent, non-destructive) are consistent with the described read/extract flow, and the description goes well beyond them: it discloses the full success return shape, the explicit refusal contract with five enumerated refusal_reason values, and the verbatim-quote evidence guarantee. This tells the agent exactly what happens when data is missing, unmatchable, truncated, or errored.

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

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

Five sentences, each carrying load: positioning, mechanism, return contract, usage guidance, and cost trade-off. The key differentiator (grounded vs. plain ask_pipeworx) is front-loaded, and the refusal enum is compact yet complete — no filler anywhere.

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 both success and refusal return shapes, closing what would otherwise be a major gap. For a tool with this routing complexity and high-stakes use, it also covers sibling differentiation, cost, failure modes, and source grounding — nothing an agent needs to invoke it 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 coverage is 100% — question and all five aliases are documented — so the baseline is 3. The description adds meaning by constraining what a good question value is: high-stakes, factual, source-answerable; the refusal reasons (not_in_source, no_tool_match) signal that off-corpus or unanswerable questions will be rejected, which informs phrasing beyond the schema's 'Your question in natural language.'

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 behavior: a hallucination-resistant answer mode that picks the right tool, fetches data, then EXTRACTS the answer using ONLY tool-result contents, with explicit refusal when data is insufficient. It clearly differentiates from the sibling ask_pipeworx via the grounding/extraction mechanism and structured evidence output.

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

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

Explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). Explicit when-not-to-use: 'prefer ask_pipeworx for casual lookups,' with the cost trade-off ('one extra LLM call') stated as the basis for choosing between the two tools.

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

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

The description deeply explains behavior: fan-out process, resolver contract, parent event extractor, news fields with fallback handling, safety short-circuits (low confidence, closed markets), wide-spread handling, and resolution-rule risk. This adds substantial value beyond the annotations (readOnlyHint, etc.) with no contradictions.

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

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

The description is very long (multiple paragraphs) and contains extensive detail. While well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), verbosity may hinder quick agent parsing. Some repetition of concepts exists.

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

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

The description covers all aspects: input types, fan-out logic, response shapes (market, analysis, evidence), resolver confidence, parent events, news fields, safety checks, cancellation rules, and illiquidity warnings. Without an output schema, it fully explains return values and edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context: 'market' accepts slug, URL, or question text; 'depth' defaults to thorough; 'include_raw' warns about response size (20KB vs 50-500KB). Examples and behavioral constraints enrich the semantics.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input forms (slug, URL, question text) and provides use cases like 'should I bet on X'. It distinguishes from siblings like polymarket_arbitrage by focusing on general research rather than specific edge or fill risk.

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

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

The description explicitly lists when to use the tool (e.g., 'should I bet on X') and provides fan-out examples for different bet types. It advises inspecting match confidence before trusting analysis. However, it does not explicitly state when not to use this tool or compare with all sibling tools.

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

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

Beyond annotations indicating safety and idempotency, the description adds valuable behavioral details: handling off-calendar fiscal years, sorting by primary metric, and returning citation URIs. 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 trigger phrases and packs significant information without wasted words. It is slightly dense but every sentence earns its place.

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

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

Given no output schema, the description explains return values (paired data, citation URIs) and data sources. It could specify response format more precisely, but overall adequate for the tool's simplicity.

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

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

Schema coverage is 100%, but the description adds meaning by explaining data sources per type and providing example inputs, thus adding value beyond the schema.

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

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

The description uses specific verbs like 'compare' and 'side-by-side comparison,' clearly states the resource (companies or drugs), and distinguishes from sibling tools by explicitly preferring this over sequential single-pack lookups.

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

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

The description provides clear context for when to use (comparing 2–5 entities) and explicitly prefers over sequential lookups. It does not explicitly mention alternatives for single-entity queries, but the sibling 'entity_profile' implies that.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already cover the safety profile, and the description adds substantial behavioral context on top: expected latency (15-60s, up to ~90s for thorough), the guarantee that findings are 'never invented', citation_uri being present only when actually resolvable, semantic excerpting instead of head-truncation, and hop/gap/contradiction behavior. No statement contradicts the annotations.

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

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

The description is long but exceptionally dense — nearly every sentence carries a distinct fact (auth gate, sibling routing, timing, citation resolvability, excerpting behavior, hop semantics). It is front-loaded with the most critical gating information (account requirement and alternative routing). Minor redundancy exists with the schema's own depth parameter description, and the citation_uri explanation is slightly verbose, preventing a perfect score.

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

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

For a high-complexity tool with no output schema, the description is remarkably complete: it covers account prerequisites, expected latency, the full return contract (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field), failure behavior (gaps[] for unanswered facets), and clear differentiation from a large sibling set of research-adjacent tools. Nothing an agent needs to decide whether and how to call it 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 coverage is 100% so the baseline is 3. The description adds real operational meaning beyond the schema — especially for depth, clarifying the differences between quick/standard/thorough in terms of hop behavior, gap recovery, contradiction scanning, and time cost — while also mapping depth tiers to account requirements. The question parameter is well-covered by the schema, so no compensation needed there.

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 precise verb and resource: grounded multi-source research across 1,517 structured data sources, with an explicit negative definition ('this is NOT open-web search'). It names the mechanism (decomposition into facets, parallel routing to 5,798 tools) and the output shape (findings packet), making it clearly distinguishable from sibling tools like ask_pipeworx and compare_entities without opening their schemas.

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

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

The description is exemplary: it explicitly states when to use this tool ('best for broad/multi-part questions over structured data') and gives specific conditions for routing to alternatives — 'for a single lookup use ask_pipeworx', 'for BREAKING or colloquial CURRENT-NEWS prefer ask_pipeworx', and 'if you are not signed in, use ask_pipeworx instead'. This is the gold standard of when/when-not guidance with named siblings.

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

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

Annotations already indicate the tool is readonly, idempotent, and non-destructive. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and states each result is 'ready to call directly, no second schema lookup needed.' This goes beyond what annotations provide.

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

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

The description is concise (3 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage guidance, and return value. 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?

The description covers what the tool returns (names, descriptions, full schemas with examples) and its role as a first-step discovery tool. It does not detail ranking criteria or error handling, but for a discovery tool with good annotations, this is sufficient. Lacks mention of pagination or performance characteristics.

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

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

Schema description coverage is 100% with all 6 parameters described. The description does not add significant new meaning beyond the schema, though it mentions 'curated examples' which are already present in the schema's examples field. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task.' It identifies the specific verb 'discover' and the resource 'tools,' distinguishing it from sibling tools like deep_research or search_news which perform actual research rather than listing available tools.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' This provides clear context for when to use the tool, though it does not explicitly list alternatives 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?

Adds significant context beyond annotations: fans out across multiple external sources, explains sources_used/sources_failed semantics, clarifies empty means 'no data' rather than an error, and describes the private-company resolved:false behavior. The readOnly/openWorld/idempotent hints are reinforced rather than contradicted.

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 examples and core purpose, but quickly becomes a dense, sprawling paragraph with many parentheticals and repeated details. It would benefit from structured bullets or clearer sectioning; while no sentence is entirely wasted, the length and run-on style reduce readability.

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

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

With no output schema, the description bears full responsibility for explaining return values and edge cases. It covers all major data sections (recent_filings, fundamentals, patents, contracts, biologics, hiring, news, LEI), denotes sources_used/sources_failed, handles name resolution and private companies, and explains input flexibility—complete for a tool of this complexity.

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

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

Schema description coverage is 100% and the parameter docs already include the same examples, zero-padding guidance, and the company/ticker interchangeability. The description adds only minor extras like 'person/place coming soon' and output-level resolved_from/resolved_to detail, which does not materially enhance parameter understanding.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme') and a precise resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates itself from single-pack SEC/XBRL/news lookups and implies a holistic profile vs. narrower siblings like resolve_entity or search_news.

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 'ALWAYS PREFER over chaining single-pask SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear condition and alternative. It also specifies accepted input forms (ticker, zero-padded CIK, or name) and how private companies are handled, leaving little 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 indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data, which is helpful beyond the annotations.

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

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

Three concise sentences: purpose, usage guidelines, and sibling references. No superfluous 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 tool with one parameter and no output schema, the description provides adequate purpose, usage scenarios, and parameter context.

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

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

Schema covers all parameter details with 100% coverage, including description of 'key.' The description only mentions 'by key,' which adds no new information beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). It distinguishes from sibling tools like remember and recall by focusing on 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Mentions pairings with remember and recall for context.

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

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

Annotations already indicate safe, read-only behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. No contradictions; provides helpful context beyond annotations.

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

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

Three sentences front-load the purpose, then explain process and use cases. No redundant words; every sentence earns its place.

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

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

Given the simple read-only tool with good annotations, the description covers input, process, output format, and use cases. It lacks mention of error handling or limitations, but is sufficient for most contexts.

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 each parameter already well-described. The description adds minimal extra meaning (e.g., 'any URL') but does not deepen understanding beyond schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It distinguishes from sibling tools by its unique function, with no overlap.

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

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

The description provides explicit use cases ('useful for') that clarify when to apply the tool, but does not specify when not to use it or mention alternatives. This leaves minor ambiguity.

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

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

Annotations already declare it as read-only, idempotent, and non-destructive. The description adds context about the data source (Currents) and that results are 'most recent' articles, which is useful. However, it does not disclose additional behavioral traits like pagination limits (beyond the max 30 in schema), rate limits, or how missing params affect results.

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 only two sentences plus an example, with no fluff. It front-loads the main purpose and includes a practical usage example. Every sentence adds value.

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

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

Given the tool's simplicity (4 optional params, no output schema, annotations present), the description covers the source, filtering options, and provides an example. It mentions list_categories to see category options, which is helpful. However, it does not specify the return format or what fields are included in each article, which might be needed by an agent.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description provides an example call, which illustrates parameter usage in context, but does not add significant new semantic information beyond what the schema already offers.

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 'Get the most recent global news articles' with a clear verb and resource, and specifies the source (Currents with 70k+ sources) and filtering by language/category. However, it does not differentiate from the sibling tool 'search_news', which might have overlapping functionality.

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

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

The description implies usage for fetching current news with optional filters and provides an example call. However, it lacks explicit guidance on when to use this tool versus alternatives like 'search_news' (e.g., for historical search) and does not mention any prerequisites or constraints.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds an example of output categories but does not elaborate on other behavioral traits like rate limits or authentication requirements. It does not contradict annotations.

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

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

The description is a single sentence with an example, front-loading the core purpose. No unnecessary words or repetition.

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

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

Given no output schema, the description could clarify the return format (e.g., list of strings), but it provides examples of the content. The tool is simple with no required parameters, so the description is mostly complete.

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

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

The input schema has 100% coverage for the single optional parameter (_apiKey), so the schema already documents it adequately. The description does not add new semantic meaning to this parameter beyond showing an example call with empty parameters.

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 news category labels supported by Currents, with specific examples (e.g., technology, business). This distinguishes it from sibling tools like search_news or latest_news, which deal with articles rather than categories.

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 an example call (list_categories({})) implying how to use it, but does not explicitly state when to use this tool versus alternatives like search_news. No guidance on prerequisites or context is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds the return fields and usage context but does not reveal additional behavioral traits 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 two sentences, front-loading the purpose and return format, then adding usage guidance. Every sentence is informative and concise with no redundancy.

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

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

Given the tool's simplicity (no required params, optional boolean, no output schema, and thorough annotations), the description is complete enough. It could clarify what 'active' means or mention pagination, but omissions are minor.

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

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

The input schema has 100% description coverage for the only parameter (include_inactive). The tool description does not add further semantics about the parameter, so it meets the baseline for schema coverage but does not exceed it.

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

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

The description explicitly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by mentioning use cases like reviewing before adding or canceling.

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

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

The description advises using the tool to review monitored subscriptions before adding more or to find an id to cancel, providing clear context for when to use it relative to siblings. It does not explicitly exclude other uses but is sufficiently directive.

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 having no useful annotation hints (all false), the description discloses critical behavioral traits: the two-mode operation (file feedback vs. retrieve with claim_token), rate limiting to 5/day, that it's free, and that it doesn't count against tool-call quota. This goes well beyond annotations.

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

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

The description is long but each sentence contributes unique information. It is front-loaded with the core purpose. Given the complexity of the tool (dual-mode, exclusions, rate limits), the length is justified, though slightly more structure (e.g., line breaks for the two modes) would improve scannability.

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 must explain return values. It does: 'returns a claim_token' and later explains using that token to see status. It also covers exclusions, rate limits, and how to identify relevant tools, making the description self-sufficient for correct usage.

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 extra meaning by explaining the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed'), which clarifies the parameter's dual purpose beyond the schema text.

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

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

The description starts with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact feedback types (bug, feature/data_gap, praise) and explicitly distinguishes itself from other MCP servers by stating it only applies to Pipeworx-served tools.

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

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

Provides explicit when-to-use guidance for each feedback type and direct when-not-to-use guidance: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also clarifies ambiguity for uncertain cases.

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 provide readOnlyHint and idempotentHint. The description adds valuable context: caching behavior (5min-1h), data source (CF analytics-engine, no PII), and self-aggregating nature. No contradiction with annotations.

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

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

The description is concise (~80 words), front-loaded with the purpose, and well-structured with bullet points for use cases. Every sentence adds value.

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

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

Given the simple read-only nature and no output schema, the description fully explains what is returned (top tools, top packs, volume), caching, and use cases. No missing information for correct usage.

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% for the single parameter 'window'. The description adds meaning by explaining that shorter windows surface what's hot now and longer windows show steady-state demand, beyond the enum labels.

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

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

The description clearly states the tool returns trending data (top tools, top packs, call volume) over a recent window. The verb 'returns' and specific resource 'Pipeworx trending' distinguish it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case with agent needs) and differentiates short vs. long windows. It lacks explicit 'when not to use', but the sibling list provides context for alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) align with the description. The description adds extensive behavioral details: scanning logic, Jaccard similarity anchor, partition filter, fill check against live CLOB depth, and reporting of skipped_low_similarity count. No contradictions.

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

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

The description is dense but front-loaded with core functionality. Every sentence adds value, though it could be slightly more structured with bullet points. No unnecessary words; it is efficient for the information conveyed.

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

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

Given the tool's complexity (multiple modes, arbitrage detection, fill check, semantic anchor, partition filter), the description covers all aspects. It explains input choices, internal logic, output structure, and references sibling tools for further details. No output schema exists, but the description compensates well.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds significant meaning: explains mode switching, provides example slugs and seed questions, and details what happens internally (walks child markets, checks ordering, computes partition_check, etc.), greatly enhancing beyond schema.

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

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

The title 'Polymarket Arbitrage' and description clearly state it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk, providing a specific verb and resource.

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

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

Explicitly describes when to use each parameter: no args for trending scan, 'event' for a specific market (recommended with slug examples), and 'topic' for cross-event scanning. Also mentions when not to trade (if realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and the description fully aligns, adding details like caching (1h at KV level), diagnostic output to explain empty segments, and the non-destructive nature. No contradictions.

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

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

The description is quite long but well-structured with clear segments (model families, knobs, diagnostics). It front-loads the core purpose and then provides necessary technical detail. Some redundancy exists (e.g., repeating knobs), but the length is justified given the tool's complexity.

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

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

With 9 parameters and no output schema, the description covers all inputs, explains the response structure (by_segment, diagnostics), describes caching, and gives guidance on interpreting edges (24h-move warning). It is fully complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema. For example, it explains min_kelly applies to single-leg opportunities only, max_spread_pp filters tight books, and slippage_pp subtracts from raw edge. It also provides default values and usage context for each parameter.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, fulfilling 'what should I bet on today'. It distinctly separates this from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx disagreement and segmentation (model-driven, structural arbitrage, concentrated longshot).

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

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

The description explains when to use the tool (opportunity discovery), mentions tradeable-edge knobs to filter, and notes that Fed bets are excluded from ranking. It does not explicitly state when not to use it or list alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), trend derivation, limitations (60-day TTL, no intraday data), and explanation of decay calculation. No contradiction with annotations.

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

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

The description is well-structured with a clear purpose sentence, detailed response breakdown, and limitations. It is slightly verbose but every sentence adds information. Front-loaded with the core question it answers.

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

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

Given no output schema, the description fully explains the return value (tracked, expired, snapshot_dates arrays) and covers limitations and edge cases (snapshot gaps, TTL). It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by specifying default values (14 for days, '1wk' for window), clamping range (2-30), and clarifying window meaning as 'snapshot family'. This exceeds the schema's minimal 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: providing edge persistence and decay telemetry built from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis.

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

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

The description gives strong contextual guidance by contrasting fresh vs. old wide edges, implying when to use this tool. However, it does not explicitly state when not to use it or directly mention alternatives like polymarket_edges for current snapshots.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds significant behavioral details: walks the ladder, returns top_of_book, vwap_fill_price, slippage, verdicts (clean|degraded|cannot_fill), and explains how basket mode works. 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?

Though lengthy, every sentence earns its place. Structured with clear sections for modes and usage. Information is dense and well-organized, front-loaded with the core purpose. No fluff; essential for a complex tool with two modes and multiple return fields.

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

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

Given no output schema, description fully explains return fields for both modes: top_of_book, vwap_fill_price, slippage, shares_filled, verdict, and basket-specific fields like capture_ratio, profit_usd, thin_legs, forced_directional_risk. Also covers edge cases (partial fills, thin books) and usage context. Complete for agent decision-making.

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

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

Schema description coverage is 100%, but description goes beyond: explains each parameter's role in both modes, default values (size_usd=1000, side default auto for basket), and interpretation (size_usd as max spend on buys, target proceeds on sells; basket as settlement notional). Adds meaningful context not in schema.

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

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

Clear verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. Explicitly distinguishes from sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', which differentiates its role.

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

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

Provides explicit guidance on when to use: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains required parameters (market or event) and default behavior for basket mode, plus warnings about partial fills leading to unhedged positions.

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

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

Annotations only say the tool is read-only, open-world, idempotent, and non-destructive. The description goes far beyond that: it discloses that compatibility flags can be non-empty even when pairs are returned, unmatched legs are explicitly skipped, matching is keyword/word-overlap based rather than source-confirmed, spreads are gross of Kalshi fees, and null temporal_alignment does not mean aligned.

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, though it is front-loaded and organized with capitalized labels like TWO MODES, RESPONSE, and SAFETY FIELDS. It repeats some content already in the schema, notably the full ten-topic list, and restates 'in EITHER mode' / 'same disclosures apply' multiple times. Structured, but not maximally concise.

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

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

With no output schema, the description must carry the burden of explaining return semantics, and it does comprehensively: spread.top_spreads_pp, compatibility_codes, low_confidence_pairs, skipped_unclassified, fees_note, temporal_alignment, and skipped counters. It also covers important edge cases such as unknown legs never being paired and temporal_alignment_unknown not meaning confirmed alignment.

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 each parameter already has concrete examples and override semantics. The description adds meaningful cross-parameter meaning by explaining the two top-level modes and that both modes 'run the identical token-overlap matcher, so the same disclosures apply to both.' This is useful but incremental on top of a well-described 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 operation: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly names the resources, the comparison, and the two modes of invocation, which distinguishes it from Polymarket-only 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 mode-selection guidance: use the ten pre-mapped `topic` shortcuts or provide explicit `kalshi_event_ticker` and `polymarket_event_slug` for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return a compatibility_warning today. It does not name sibling tools as alternatives, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds scoping detail (by identifier) and listing behavior, but doesn't contradict annotations. Adds moderate value beyond annotations.

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

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

Four concise sentences, front-loaded with main action. No unnecessary words or repetition. Efficient.

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

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

With no output schema, the description explains return types (value or list of keys) but doesn't detail format. Given low complexity (1 optional param), it's sufficiently complete for agent usage.

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

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

Schema coverage is 100%, with the schema describing the key parameter. The tool description repeats that omitting key lists all keys, adding no new semantics. Baseline 3 is appropriate.

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

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

Clearly states the tool retrieves saved values or lists keys, with specific verb ('retrieve') and resource ('values saved via remember'). Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Provides examples (ticker, address, notes) and mentions scoping. No explicit when-not-to-use, but pairing with siblings is implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the behavioral detail that setting mark_read:true flags events as read, affecting subsequent calls. No contradictions.

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

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

Concise yet informative: 4-5 sentences, each adding value. Front-loaded with the core purpose, then details on returned fields, filtering, and an alternative endpoint. No redundant 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?

Covers return values (source, citation_uri, raw payload) and all parameters. Lacks mention of pagination for high limits but is sufficient given the tool's simplicity and the presence of a limit parameter.

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 each parameter having a description. The tool description adds practical usage examples (e.g., 'sec_8k' type, ISO timestamp) and explains the effect of mark_read, going beyond the schema alone.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts with specific data fields (source, citation_uri, raw payload). It is distinct from sibling tools like subscribe, unsubscribe, or list_subscriptions by being a read operation.

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

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

Provides guidance on when to use (polls work fine) and points to an alternative endpoint for scripts/dashboards. Lacks explicit 'when not to use' but gives clear context for filtering and mark_read behavior.

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

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

Annotations already indicate readOnly, idempotent, and nondestructive. Description adds beyond that: it fans out to multiple sources in one parallel call, mentions GDELT→GNews fallback, and notes the patents API soft-fails. No contradiction.

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

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

The description is dense but well-structured, front-loading the purpose and query examples. Every sentence serves a purpose, though length could be slightly reduced.

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

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

Covers all key aspects: sources, fallback, syntax for 'since', return structure (changes[] grouped by source, total_changes count, citation URIs). No output schema, but description provides enough detail on what is returned.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context for 'since' (ISO date or relative shorthand) and explains the news fallback, but does not significantly expand beyond schema's own 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 ('change feed') and resources ('SEC EDGAR', 'GDELT→GNews', 'USPTO'), and clearly distinguishes from sibling tool 'entity_profile' by stating when to use that instead.

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

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

Explicitly gives example queries ('What's new with X', 'latest on Y'), explains the scope ('in the last N days/weeks/months'), and provides an alternative ('Use entity_profile instead'). Also describes fallback behavior for news sources.

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 provided (idempotentHint: true, destructiveHint: false). Description adds context: key-value scoped by identifier, persistent vs 24-hour retention, no contradictions.

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

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

Four concise sentences, front-loaded with purpose, 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?

No output schema, but description covers use cases and lifetime. Could mention confirmation or error, but sufficient for a simple write 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 has 100% coverage, baseline 3. Description adds value by providing examples for keys (e.g., 'subject_property') and explaining what values can be (findings, addresses, etc.), slightly beyond schema.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, distinguishing from siblings like recall and forget.

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

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

Explicitly says when to use (when discovering information to carry forward), pairs with recall/forget, and describes persistence differences between authenticated and 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 goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit listing of unresolved identifiers, handling of ambiguous matches via figi_candidates, and the fact that it accepts multiple input formats. There is no contradiction with annotations; rather, the description enriches the behavioral model the agent needs.

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 densely informative. It front-loads the core purpose and then systematically covers supported types, return behavior, edge cases, and fallbacks. Every sentence contributes unique value—there is no fluff or repetition. Some redundancy exists (e.g., repeated emphasis on entity name only), but it is not excessive. Score 4 reflects that it is appropriately structured for the tool's complexity rather than truly concise.

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

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

With no output schema, the description fully compensates by explaining what each type returns (CIK, ticker, LEI, FIGI for companies; RxCUI, ingredient, brand for drugs), how ambiguous cases are handled (figi_candidates), and how resolution degrades gracefully. It also covers accepted input formats and the special ISIN-to-LEI path. There are no major gaps an agent would need to ask about.

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 crucial semantic detail: it provides concrete examples for the value parameter (e.g., 'AAPL', '0000320193', 'ozempic') and warns about passing only the entity name for bonds (avoiding trailing security-class words). This addresses pitfalls not captured in the schema and materially improves correct invocation.

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

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

The description states a specific verb (resolve), a resource (entity names → identifiers), and the exact use case: converting user-spoken names into canonical/official IDs required by other tools. It distinguishes itself as the first step in that workflow ('Use FIRST whenever you have a name but need an ID') and lists concrete query examples ('What's the ticker for…', 'find the CIK for…') that 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 explicitly instructs when to use the tool ('Use FIRST whenever you have a name but need an ID') and explains the types it covers (company, drug) with details on what each resolves. It also notes that it replaces 2-3 manual lookups, implying it is the most efficient path. However, it does not explicitly contrast with sibling tools like entity_profile or compare_entities, nor state when NOT to use it (e.g., if you already have an ID). This is a minor gap.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. It does not disclose additional behavioral traits like rate limits or API key handling beyond the schema. This 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 two sentences with no redundancy. The first sentence states the primary function, and the second provides a use case example and output summary. Every word adds value, achieving high 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?

The tool has 4 parameters and no output schema. The description explains the probing mechanism, ranking logic, and output format (ranked list with score, confidence, signal density). It also provides an example query. This is sufficient for an agent to understand what to expect, though a bit more detail on the output structure would be ideal.

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 schema already documents all parameters. The description adds value by stating that the first entity is treated as the 'subject' for narrative, which is not in the schema. This improves semantic understanding beyond the structured field 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each entity. It distinguishes from the sibling tool ai_visibility_check (single entity) and other comparison tools by specifying the output is a ranked list with scores. The specific use case of competitive AI-marketing audits adds clarity.

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits and implies it should be used when comparing multiple entities. It does not explicitly list when not to use it or mention alternative tools like compare_entities, but the context is clear enough for an agent to decide.

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

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

Annotations already mark the tool as non-destructive and idempotent; the description adds crucial context: partial failures, bundlephobia's 5-30s timeout, and graceful degradation via 'sources_failed' list. No contradictions.

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

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

Dense but well-structured: purpose first, then use cases, output summary, limitations. Every sentence adds necessary information without fluff.

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

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

Despite no output schema, the description comprehensively lists return fields and explains dynamic behavior (partial failure, timeout). Complete for a composite multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining scoped package acceptance and version default behavior, exceeding mere schema repetition.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, specific verb ('scan dependency'), resource ('npm package'), and distinguishes from sibling tools like resolve_entity or deep_research.

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

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

Explicitly indicates when to use ('whenever an agent asks 'is X safe / popular / small'') and mentions limitations (NPM only; other ecosystems via deps.dev), providing clear context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the source ('Currents with 70k+ sources') and an example, but does not disclose behavioral details beyond what annotations provide (e.g., rate limits, response structure). It adds marginal value.

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

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

The description is two sentences plus an example, with no superfluous words. The first sentence states the core purpose, the second lists filters, and the example illustrates usage. Every part 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?

The tool has 8 parameters and no output schema, so the description should hint at the return format. It mentions 'Search global news' but does not describe what is returned (e.g., article titles, links, snippets). For a search tool, this is a notable omission. However, it does cover the source and filtering options adequately.

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 schema already documents all parameters. The description lists filters (language, category, country, date range) and gives an example, but adds no new meaning or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Search' and the resource 'global news' across 'Currents (70k+ sources)'. It specifies filtering options (language, category, country, date range) and provides an example, making the purpose unambiguous. This distinguishes it from siblings like 'latest_news' which likely returns recent headlines without keyword search.

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

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

The description implies usage for keyword-based news search with filters but does not explicitly state when to use this tool over alternatives like 'latest_news' or 'list_categories'. No when-not or exclusions are provided. The example helps but lacks comparative 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?

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character cap (200K with truncation flag). Annotations already indicate safety (readOnlyHint) and idempotency, so description adds valuable technical behavior beyond annotations.

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

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

Single paragraph is concise, front-loads the core purpose, and every sentence adds value. No wasted words; structure is logical and easy to parse.

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

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

Despite lacking an output schema, the description explains return values (top-N passages with offsets and scores). It also covers technical details like embedding and truncation. For a tool with 3 parameters, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. Description provides examples for 'query' and repeats schema info for 'text' and 'limit', but does not add substantial new meaning beyond what the schema already offers.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by noting it's for large records that don't fit in the prompt and pairs with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative tool (ask_pipeworx_grounded). This gives clear when-to-use and when-not-to-use guidance.

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

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

The description goes beyond annotations by detailing authentication requirements, persistence of subscriptions, type-specific parameters, delivery channels, and constraints (SMS cap, phone verification, webhook signing). It aligns with annotations (readOnlyHint=false, idempotentHint=true) and adds rich behavioral context.

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

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

The description is well-structured with clear sections for purpose, return, prerequisites, types, and delivery. It is front-loaded with the main action. While slightly verbose, every sentence adds value, and the structure aids readability for an AI agent.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers purpose, parameters, return value, authentication, types, delivery, and limitations. It references related tools (recent_alerts) and mentions the always-on feed. Minor gaps: doesn't explain error scenarios or idempotency behavior, but overall comprehensive.

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 substantial value by providing concrete examples for each type's params, explaining delivery options' requirements (e.g., phone verification, email pattern, webhook signing), and noting the one-time delivery of webhook secret. This enhances understanding beyond the schema.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It also specifies the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account, no anonymous/BYO) and detailed examples for each subscription type. However, it does not explicitly state when not to use this tool (e.g., for listing or unsubscribing), though sibling tools exist. It includes delivery channel guidance and limitations like phone verification and SMS cap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns organized example questions with tool+argument shape, and is drawn from a live catalog. No contradictions.

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

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

The description is somewhat long but front-loaded with example queries. Each sentence adds value, but it could be slightly more concise. For a discovery tool, the verbosity is acceptable and serves clarity.

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

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

Given there is no output schema, the description fully explains what the tool returns (category-bucketed examples with tool shapes) and how to use it. It covers the 'what', 'when', and 'how', making it complete for agent decision-making.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning beyond the schema by listing example topic values and specifying behavior when omitted ('full spread' vs. focused). This provides practical guidance for agent invocation.

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

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

The description clearly states what the tool does: returns category-bucketed example questions with tool arguments. It distinguishes itself from siblings by being the onboarding entry point, using verbs like 'returns' and 'use this FIRST'.

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

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

Explicitly provides when to use: 'when you do not yet know what Pipeworx can do for you' or 'to learn how to call the meta-tools'. Also explains when to pass a topic vs omit, and briefly mentions alternatives like meta-tools.

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

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

Description adds ownership enforcement and deactivation semantics beyond annotations, which already indicate non-read-only, idempotent, and non-destructive. No contradictions.

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

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

Two sentences, front-loaded with main action, no wasted words. Every sentence adds value.

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

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

For a simple one-param tool with no output schema, it covers purpose, ownership, effect (deactivation), and connection to sibling tool recent_alerts. Complete.

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

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

Schema coverage is 100% with clear description of 'id' parameter. Description does not add extra meaning beyond 'by id', 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?

Clear verb 'Cancel' and resource 'subscription'. Distinguishes from sibling subscribe (opposite) and explains deactivation vs deletion, making the tool's purpose specific.

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

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

States ownership enforcement and deactivation behavior, providing context for when to use. Does not explicitly mention when not to use or list alternatives like subscribe or list_subscriptions, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: verdict types, the meaning of could_not_verify vs unsupported, the error structure with stage/detail, the dual pipeline routing, and the citation return. This goes well beyond the annotations and clearly explains edge-case behaviors.

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

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

The description is fairly long but well-structured, front-loading with trigger phrases and core purpose before diving into pipeline details and verdict semantics. All sentences carry useful information, though some could be tightened (e.g., the final 'Replaces 4–6 sequential calls' is an efficiency note that might be implied). Overall, it's appropriately sized for a complex tool.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains return values (verdicts, grounding citation, reasoning), error semantics (could_not_verify with verification_error), and the distinction between unsupported and could_not_verify. It covers both the financial fast path and general grounded pipeline, making the description complete for an agent to understand behavior without needing an output schema.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description further enriches meaning by providing concrete claim examples, explaining how tolerance_pct overrides implied wording, defaulting to 5, and providing use-case guidance (1–2 for hallucination detection). This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases and examples. It distinguishes itself from siblings by focusing on fact-checking and explains the two pipelines (SEC/XBRL for company financials, grounded for everything else). This is a specific verb+resource description with clear 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?

The description explicitly says to use it 'whenever the agent needs to check whether something a user said is factually correct' and provides example query forms. It also notes it replaces 4–6 sequential calls, implying efficiency. However, it doesn't explicitly name alternative tools for non-fact-checking research, so it lacks explicit exclusions.

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