Us News Feeds

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false. The description adds that the default model is free, Anthropic requires user's key, and returns per-model {score, confidence, signals, raw_response} plus combined view. No contradictions and adds significant behavioral context beyond annotations.

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

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

Two well-structured sentences. First sentence states core purpose. Second sentence adds key details on default model and API key. Final sentence mentions returns and use cases. Efficient and front-loaded.

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

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

Given the tool has 4 parameters, no output schema, and high schema coverage, the description covers purpose, parameters, return format, and use cases completely. It stands alone without needing further explanation.

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

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

Schema description coverage is 100%, and the description enriches each parameter: entity with examples, models with defaults, _apiKey with when needed, context with disambiguation purpose. This adds full semantic clarity.

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 knowledge about a business/brand/product/topic and scores visibility 0-100 per model. It specifies default model (Workers AI Llama-3.3-70b) and optional Anthropic probing. This distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the free default vs. pay for Anthropic. It could explicitly mention when not to use, but the given guidance is clear enough.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context beyond these: the scale of sources, filling arguments, stable pipeworx:// citation URIs, and performance characteristics ('one fast call'). No contradictions, though it does not disclose potential failure modes or limitations.

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

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

The description is long but front-loaded with the critical directive ('PREFER OVER WEB SEARCH') and organized with examples and clear alternatives. Some redundancy exists, such as repeating 'works on every tier' and 'one fast call,' which slightly reduces conciseness. Overall, every sentence contributes to usage guidance, though a tighter edit would improve structure.

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

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

There is no output schema, but the description compensates by explaining the return format ('structured answer with stable pipeworx:// citation URIs') and covering a broad range of question types. It also names step-up alternatives and states it works on every tier, providing sufficient context for the agent to invoke it correctly across diverse factual queries.

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

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

The schema covers all 6 parameters (all aliases for 'question') with 100% description coverage, so the baseline is 3. The description provides example questions and notes that multiple aliases are accepted, but it does not add deeper meaning to the parameter beyond confirming natural-language usage. No additional syntax or constraints are documented 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 starts with 'PREFER OVER WEB SEARCH' and clearly states it routes questions to 5,462 tools across 1,419 verified sources, returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It gives explicit when-to-use guidance: 'START HERE for most questions', 'Step up only when needed' for grounded/deep_research, and notes it covers breaking news via live news feeds. It also lists trigger phrases ('what is', 'look up', 'find', etc.) to help the agent decide when to invoke this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds meaningful context: it is a beta with live candidate routing improvements, currently matches ask_pipeworx exactly, and is a full working router that falls back to nothing. This discloses the experimental nature and current state, which annotations do not cover.

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

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

The description is a single well-structured paragraph that front-loads the key identity (beta version of ask_pipeworx) and then efficiently covers current state, usage, and behavior. Every sentence contributes meaningful information without unnecessary repetition.

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

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

Despite no output schema, the description states 'same response shape' as ask_pipeworx, which covers return values for agents familiar with that tool. It also explains the routing comparison and experimental status. This is sufficiently complete for the tool's role as a beta variant, though it relies on reference to ask_pipeworx for details.

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

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

The schema provides 100% coverage with descriptions for all six parameters (all aliases for question). The description only states 'same arguments' without adding syntax or format details. It adds no value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,462 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements and the experimental edge.

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

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

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and clarifies that results are compared against the stable router. It doesn't explicitly state when not to use, but the beta/experimental framing implies caution in production contexts.

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 annotations by detailing the exact return format, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the use of verbatim evidence, and the extra LLM call cost. This adds rich behavioral context that annotations (readOnlyHint, etc.) do not convey.

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

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

The description is dense but structured, starting with purpose, then behavior, return format, usage, and cost tradeoff. Every sentence contributes meaningful information, with no fluff or redundancy, making it highly efficient for an agent to parse.

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

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

Despite lacking an output schema, the description fully specifies the return format and failure modes, and explains the comparison to ask_pipeworx. Given the tool's complexity and the absence of output schema, this description covers all necessary context comprehensively.

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 all parameters are already documented. The description adds no parameter-specific semantics beyond what the schema provides; it only mentions 'fills arguments' conceptually. Baseline 3 is appropriate since the schema handles the parameter details.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that extracts answers using only tool results, and explicitly distinguishes from sibling ask_pipeworx by mentioning 'Same routing as ask_pipeworx' but with grounded extraction. This gives a specific verb (ask) and resource (Pipeworx), with clear differentiation.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups.' It even names the alternative and the tradeoff (extra LLM call), making the decision unambiguous.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: safety mechanisms (low-confidence short-circuit, closed market handling, wide spread tradeability), resolution-rule risk, fan-out parallelism, and response shapes. 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 very long and covers many details, but it is structured with capitalized section titles and clear examples. While comprehensive, it could be more concise for quicker agent parsing. The front-loading of purpose is good, but overall verbosity reduces conciseness.

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

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

Given the complexity (3 parameters, no output schema, many edge cases), the description is extremely complete. It covers input formats, behavioral nuances, response structure, safety, resolution rules, and provides examples. Agents have sufficient context to use this tool correctly.

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

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

Schema coverage is 100% with 3 parameters. The description adds significant meaning: market can be slug/URL/text; depth explains quick vs thorough, default thorough; include_raw explains when to use true (recomputing deltas, post-processing). This goes beyond the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data, and lists specific input formats (slug, URL, question text). It provides use cases like 'should I bet on X'. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, though the use cases imply a distinct purpose.

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

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

Explicitly states when to use the tool ('Use for...') and provides classifiers, fan-out examples, and warnings about low-confidence matches, closed markets, and wide spreads. It implicitly discourages use when confidence is low, but does not directly mention when to use alternative tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable details: data source (SEC EDGAR, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs. No contradictions.

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

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

Description is front-loaded with example queries, then explains behavior, data sources, and result ordering. Every sentence is informative and concise (~120 words). No fluff.

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

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

Given 2 params, 100% schema coverage, and no output schema, the description is nearly complete. It covers purpose, usage, and behavioral details. Minor gap: doesn't specify return format (table vs JSON), but agent can infer from 'paired data + citation URIs'. Almost perfect.

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

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

Schema coverage is 100% with clear descriptions for type (enum) and values (array with min/max). Description adds context: type='company' pulls revenue/net income/cash/debt; type='drug' pulls adverse events/approval counts/trials. This complements schema well.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, with example queries like 'compare X and Y' and 'rank these companies'. It distinguishes from single-entity lookups (entity_profile) and general Q&A (ask_pipeworx).

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. Also gives example queries that trigger this tool, implying when not to use it (single entity queries).

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals account requirements, parallel decomposition, return packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), gap-recovery and iteration behavior for different depths, semantic excerpting, and expected latency (15-90s). It also states 'never invented' and clarifies citations are resolvable pipeworx:// URIs, adding substantial behavioral context that annotations don't cover. No contradiction exists.

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

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

Although the description is long, it's front-loaded with the most critical constraint ('ACCOUNT REQUIRED...') and the fallback alternative, then logically flows from what the tool does → how it works → when to use → depth semantics → citation guarantees → performance. Every sentence contributes unique, actionable detail, and no filler or repetition of schema fields exists. Given the tool's complexity, the length is justified.

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 detail return values, which it does comprehensively: findings packet components, gaps[] for unanswerable facets, contradictions[] for standard/thorough, hop field, and citation_uri. It also covers account/pricing prerequisites, timing expectations, and behavior for out-of-catalog topics (empty gaps[]). This covers all critical operational aspects for an agent to decide on and invoke the tool correctly.

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

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

The input schema already documents both parameters with 100% coverage, providing a baseline of 3. The description adds value by explaining that `question` can be broad/multi-part, and details the `depth` options (quick=3, standard=5, thorough=8) with paid-tier requirement for thorough, as well as what each depth does. This supplements the schema's descriptions, though the schema itself already covers a good deal.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and explains that it 'Decomposes your question into focused facets, routes each to the right one of 5,462 tools IN PARALLEL, and returns a findings packet.' It explicitly distinguishes itself from open-web search and sibling ask_pipeworx, making its unique purpose unmistakable.

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

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

The description states 'Best for broad/multi-part questions over structured data' and gives explicit alternatives: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS / "what's the world saying about X" topics, prefer ask_pipeworx.' It also notes that if not signed in, use ask_pipeworx instead, covering when-not-to-use and naming specific sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotent=true, and destructiveHint=false. The description adds that results include full input schemas with curated examples and are ready to call, which is helpful but not critical 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 well-structured with front-loaded purpose. It contains multiple sentences but each adds value. Slightly verbose but efficiently communicates key 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?

No output schema is provided, but the description adequately explains the return format (top-N tools with names, descriptions, schemas) and that results are ready to call. Sufficient for a lookup tool.

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

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

Schema description coverage is 100%. The description adds value by listing aliases (task, q, description, search) and providing examples, enhancing understanding of the 'query' parameter 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 ('Find', 'browse, search, look up, discover') and a clear resource ('tools'), listing many domains. It distinguishes from siblings like 'search_within' by focusing on tool discovery.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (when you need a specific answer).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond annotations: it details the multiple data sources fanned out across (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists specific return fields (cik, filings with URIs, fundamentals, patents, news, LEI), notes that the patents source 'soft-fails until reactivated,' and describes the internal filing URIs. 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 relatively long but every sentence serves a purpose: query examples, usage preference, input restrictions, data sources, return fields, and caveats. It is front-loaded with common user intents, enhancing quick scanning. A minor reduction in internal details (e.g., explicit list of all return fields) could improve conciseness, but overall it is well-structured and efficient.

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

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

Given the tool's complexity (multiple data sources, varied output), the description is remarkably complete. It enumerates all returned data fields (cik, company_name, filings with URIs, fundamentals sorted by period_end, patents, news via GDELT→GNews, LEI), notes limitations (patents soft-fail, names not supported), and mentions the internal URI format. Without an output schema, this description fully informs the agent about expected results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by clarifying that 'type' is currently limited to 'company' and explaining the acceptable formats for 'value' (ticker or zero-padded CIK). It also explicitly states that names are not supported and directs to 'resolve_entity' if only a name is available, which is not in the schema. This enriches the parameter meaning.

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

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

The description clearly states the tool's purpose as generating a full cross-source profile of a US public company in one call, with specific verb ('get'), resource ('US public company'), and scope. It distinguishes from sibling tools by emphasizing preference over chaining individual lookups, and provides example queries that illustrate typical use cases.

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

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

The description explicitly advises to 'ALWAYS PREFER' this tool over chaining single-source lookups for holistic views. It specifies valid inputs (ticker or CIK) and explicitly excludes names, directing users to 'resolve_entity' for name resolution. This provides clear when-to-use and when-not-to-use guidance, with an alternative tool named.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint). Description adds value by revealing the proxy fallback mechanism and normalization behavior. No contradictions. Additional traits like rate limits or auth are not needed given 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, front-loaded with purpose. Each sentence serves a distinct role: action, robustness, usage guidance. No redundant or unnecessary information.

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

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

For a simple fetch tool with no output schema and rich annotations, the description covers the essentials: what it does, how it handles failures, and when to use alternatives. Minor omission of return format but not critical given tool 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% with clear parameter descriptions. The description adds no further parameter-specific meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Fetch and normalize' and the resource 'any RSS / Atom / RDF feed by URL.' It differentiates from sibling tools like 'list_feeds' (curated sources) and 'read_feed', establishing a unique purpose.

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

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

Provides explicit guidance: 'Use list_feeds first for curated sources.' Also mentions CF-robust fallback behavior, which implies when this tool is advantageous. Lacks explicit when-not-to-use scenarios but offers clear 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 provide destructiveHint and idempotentHint. Description adds context about clearing sensitive data, but doesn't disclose if deletion is permanent or undoable.

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, no wasted words. First sentence states action, second gives usage guidance.

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

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

Adequate for a simple tool with one parameter and no output schema. Could mention permanence but overall 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. Description adds minimal extra beyond 'by key'. Baseline 3 for high coverage.

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

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

Clear verb 'Delete' and resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Also recommends pairing with remember/recall.

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. The description adds valuable behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown. No contradictions with annotations.

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

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

The description is a single paragraph of three sentences, each sentence adding meaningful information: action, process, use cases. No filler or redundancy.

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

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

Despite no output schema, the description explains the output format (standard llms.txt markdown) and destination (site-root/llms.txt). It covers use cases and constraints. For a simple tool with 2 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% and both parameters are described in the schema. The description restates the 'url' and implies 'max_links' via default/max values, but adds little beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generate a standardized llms.txt file for any URL. It uses specific verbs (Generate, Fetches, extracts, emits) and specifies the output format. No sibling tool appears directly similar, so it is well-distinguished.

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: getting a client's site indexed, drafting for own project, and auditing competitor. While it doesn't mention when not to use, the positive scenarios are clear and helpful for an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds value by mentioning the returned fields and the filtering behavior, but does not cover pagination or ordering. Still, it is sufficiently transparent for a read-only list tool.

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 (two sentences), front-loads the core purpose, and contains no unnecessary 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?

Given the tool's simplicity (2 optional parameters, no output schema, clear annotations), the description covers all necessary aspects: purpose, scope, filters, and relationship to a sibling. No gaps are evident.

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

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

The input schema already provides descriptions for both parameters with 100% coverage. The description reinforces these filters but does not add significant new meaning beyond what the schema states. 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 action as listing curated US news, politics & government feeds, specifies the returned fields (id, title, category, source), and explicitly distinguishes the sibling tool read_feed by directing users to pass an id there.

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 context for when to use this tool (list with optional filtering) and when not (if you have a feed id, use read_feed). It also lists the two filtering options with example values.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint false). Description adds return field names and scoping, which is useful but not extensive. No mention of pagination or limits, but given simplicity, it's adequate.

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

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

Two sentences, no wasted words, effectively front-loaded with the core action.

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

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

Despite no output schema, the description lists all return fields. For a simple list tool, this is fully 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 a clear description for 'include_inactive'. Description does not elaborate beyond schema, so baseline 3 applies.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions'. It specifies the return fields and distinguishes from siblings like 'subscribe' and 'unsubscribe' by being a listing 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?

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use this tool vs 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 are all false, so no safety profile is given; the description compensates by disclosing rate-limiting ('5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and the team's daily digest review. It omits specifics like persistence or whether feedback is anonymous, but the key behavioral constraints are covered.

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

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

The description is long but every sentence earns its place: purpose, use cases, exclusion, message guidance, and rate limit. It is front-loaded with the core purpose and stays on-topic 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?

For a low-complexity feedback tool with no output schema, the description thoroughly covers what the tool does, when to use it, what to include, exclusions, and operational constraints. The nested 'context' parameter is already documented in the schema, so no gap remains.

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 meaningful guidance for the 'message' parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and reinforces context usage by explaining which tools are relevant. This goes beyond the schema but not by a huge margin.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this feedback tool from siblings like 'ask_pipeworx' and 'discover_tools' by framing it as reporting issues, gaps, or praise about Pipeworx tools.

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

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

The description explicitly states when to use it ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). This is exceptionally clear guidance with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. Description adds valuable context: self-aggregating, no PII, cached 5min-1h depending on window. No contradictions.

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

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

Description is three sentences plus a bulleted list, all front-loaded with the core function. Every sentence adds value with no redundancy or fluff.

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

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

For a simple read-only query tool with one parameter and comprehensive annotations, the description covers all needed behavioral and usage context (caching, data source, privacy). No output schema needed; return values are intuitive.

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 parameter 100% with enum and description. Description expands by explaining window semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds meaningful guidance beyond schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. It provides specific use cases, making the purpose immediately understandable and distinct from sibling tools.

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

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

Explicitly lists three useful scenarios: discovering hot data sources, confirming canonical tools, and checking use case alignment. While it doesn't explicitly state when not to use it, the guidance is clear and practical.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: it performs checks against live CLOB depth, has semantic anchor and partition filter logic, and warns about realizable_edge_pp <= 0 meaning the opportunity is not actionable. 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 comprehensive but somewhat verbose. It is well-structured: starts with purpose, then covers each mode, then details fill check, and ends with an alternative tool. While it earns its length, it could be tightened slightly without losing clarity.

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

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

Given the complexity (multiple modes, internal checks, live data interaction), the description is very complete. It covers what each mode returns, the partition filter, the fill check, and when to use another tool. The absence of an output schema is compensated by explaining return fields like 'gap_pp', 'suggested_trade', etc. The annotations further support completeness.

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

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

Schema coverage is 100% with both 'event' and 'topic' parameters described. The description adds significant meaning: explains what event slugs look like, provides examples, details how each mode uses the parameter, and describes the internal logic (e.g., Jaccard similarity threshold). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes multiple modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_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 provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains when not to trade based on fill check results and recommends 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 already declare safe read-only behavior. Description adds caching (1h KV-level), diagnostics (funnel counters, filter_skips), and cautious note about Fed data unreliability. 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?

Front-loaded with purpose, then segments, then knobs, then response structure. Somewhat long but each detail serves a purpose. Could be slightly tighter but well-organized.

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

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

Very comprehensive: explains three segments, opportunity fields, knobs, response top-level including diagnostics and Fed note. No output schema, but return values are described. Covers all essential aspects.

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%, baseline 3. Description adds significant value: explains tradeable-edge knobs (min_liquidity, max_spread_pp), why min_kelly doesn't filter partition arbs, and slippage_pp context with Polymarket fees.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. Differentiates from siblings by focusing on Pipeworx disagreement.

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

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

Provides clear use case ('what should I bet on today') and explains the three segments and Fed bet exclusion. Lacks explicit when-not-to-use or direct comparison with sibling tools like polymarket_arbitrage, but context is sufficient.

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

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

Annotations indicate read-only, idempotent, and non-destructive. The description adds behavioral details: uses daily snapshots, decay computed from daily closes (not intraday), 60-day TTL, and explains response structure with tracked, expired, and snapshot_dates. No contradictions.

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

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

The description is front-loaded with the main purpose, then details response and limits. It is somewhat lengthy but every sentence adds value. Could be slightly more concise but still 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?

Without output schema, the description thoroughly explains the three parts of the response (tracked[], expired[], snapshot_dates[]) and their fields. It also covers limits like TTL and decay computation. Complete for the tool's complexity.

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

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

Input schema already provides descriptions for both parameters (days, window) with defaults and ranges. The description adds context about snapshot families and lookback limits but does not significantly enhance understanding beyond schema. High schema coverage (100%) sets baseline at 3.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series and decay.

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 context on when to use (e.g., comparing fresh vs. old wide edges) and implies it is for historical analysis, but does not explicitly state when not to use it or name alternatives like polymarket_edges for current data.

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, non-destructive. The description adds rich behavioral context: it walks the ladder, returns verdicts (clean|degraded|cannot_fill), identifies forced directional risk legs, and explains basket mode specifics. 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 lengthy but well-structured with bold labels (SINGLE-MARKET, BASKET) and bullet-like enumeration of return fields. Every sentence adds value, though it could be slightly more terse without losing key details.

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

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

Despite lacking an output schema, the description thoroughly documents all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains edge cases like thin_legs and forced_directional_risk. This is highly complete for a complex tool with 4 parameters and two operational modes.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description elaborates on defaults (size_usd default 1000, side default for each mode), constraints (clamp 10-1,000,000), and interpretation differences between single-market and basket modes, adding significant 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 explicitly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly separates two modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-action risk check.

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

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

The description provides clear guidance on when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the consequence of not using it (partial fills convert arb to unhedged directional), which is the dominant loss mode.

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

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

Annotations already declare readOnly, idempotent, not destructive. The description adds significant context: it explains compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and dropped comparison counters. 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 lengthy but front-loaded with the main purpose and modes. Every sentence adds value, explaining safety fields and typical results. A slight trim could improve conciseness, but it remains well-structured.

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

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

Given the tool's complexity (spread calculation, multiple venues, compatibility checks, temporal alignment), the description is complete. It covers output fields (prices, spreads, safety warnings) without an output schema, and provides realistic expectations about tradeability.

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

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

Schema coverage is 100% with descriptions. The description enriches parameters by explaining the logic behind topic mapping and how explicit parameters override the topic. It adds context beyond the schema, though the schema already covers basic meaning.

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

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

The description clearly states it calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs (compute, compare) and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue differences.

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

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

It explicitly describes two modes (topic shortcuts vs explicit tickers), gives examples, and warns that most pre-mapped topics return compatibility warnings. It tells when to use (to find spreads) and when not (when bet shapes aren't equivalent), with detailed conditions in safety fields.

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?

Descriptive beyond annotations: states return format (title, link, published, summary) and filtering capability. Annotations already declare read-only, idempotent, non-destructive; 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?

Two sentences with front-loaded purpose and essential details. No redundant information; 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?

Covers purpose, parameters, and return format despite no output schema. Missing details on sorting or time range, but sufficient for a curated feed reader given sibling context.

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

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

Schema coverage is 100% and description adds value by linking feed parameter to list_feeds output. Also clarifies limit range and query scope. Exceeds baseline of 3.

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

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

The description clearly states the verb 'Read' and the resource 'curated US news, politics & government feed', specifying it uses an id from list_feeds. This distinguishes it from generic feed tools, though it doesn't explicitly differentiate from sibling 'fetch_feed'.

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?

Implies using list_feeds first to get feed IDs and mentions optional keyword filtering. Provides clear context for when to use, but lacks explicit alternatives or when-not-to scenarios.

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

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

The description adds useful behavioral context beyond annotations: scoped to user identifier (anonymous IP, BYO key hash, account ID). Annotations already indicate read-only, idempotent, non-destructive, so description complements without redundancy. 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 two sentences, front-loading the core function. Every sentence adds value: first explains dual behavior, second gives usage context. No redundant or irrelevant information.

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

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

Given the tool's simplicity (one optional parameter, no output schema, good annotations), the description covers all essential aspects: what it does, when to use it, scope, pairing. The agent has sufficient information to invoke it correctly.

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

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

Schema coverage is 100% (one parameter with description). The description further clarifies that omitting the key lists all saved keys, which is consistent with the schema but adds operational context. This goes beyond what the schema alone provides, justifying above baseline.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It uses a specific verb (retrieve/list) and resource (memory keys/values). Sibling tools remember and forget are explicitly mentioned, distinguishing it from alternatives.

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 this tool (to look up context stored earlier, without re-deriving it) and mentions pairing with remember and forget. However, it does not explicitly state when not to use it or provide alternative tools beyond the pairing.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, etc. The description adds value by disclosing the mark_read parameter behavior, which could be seen as a write operation. It also describes the return fields. No contradiction with annotations, but the mark_read disclosure is important and well-explained.

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

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

The description is three sentences and gets to the point quickly. It could be slightly more structured, but it is efficient and front-loaded with the main purpose. 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 lack of an output schema, the description adequately covers return fields (source, citation_uri, raw payload) and explains optional filtering and mark_read behavior. It provides sufficient context for an agent to understand what results to expect and how to use the tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds minimal extra meaning beyond what's in the schema, e.g., explaining that polls work fine and the alternative endpoint. The description does not significantly 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 clearly states the tool pulls recent alerts from a subscription feed, specifying the resource and verb. It mentions the kind of data returned (source, citation_uri, raw payload). However, it does not explicitly differentiate from sibling tools like fetch_feed or read_feed, though the purpose is distinct enough.

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 notes that polling works fine and provides an alternative access method (GET registry.pipeworx.io/alerts.json), giving context on usage. It does not explicitly list when to use this tool versus alternatives, but the context is clear enough for an agent.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the fan-out to multiple data sources, fallback from GDELT to GNews, soft-fail for USPTO API, and the return structure (grouped changes with citations). This adds significant 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 a single paragraph but effectively front-loads example queries and clearly structures the purpose, data sources, parameters, and sibling differentiation. While dense, it contains no wasted words; minor structural improvements (e.g., bullet points) would not add much 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?

The description covers the return format, data sources, parameter details, and sibling relation. Without an output schema, it gives a sufficient overview. It does not specify maximum window size or rate limits, but these are acceptable gaps given the read-only and idempotent nature.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the since parameter format (ISO date vs relative shorthand like "7d", "30d") and the value parameter (ticker or CIK), and notes that type is currently limited to "company". This enhances the schema descriptions.

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

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

The description clearly defines the tool as a change feed for a company within a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasting with the sibling tool entity_profile (static profile). Example queries like "What's new with X" tie usage to natural language.

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 guidance on when to use this tool (for dynamic updates over a window) and when to use entity_profile instead (for static profile regardless of window). It also explains the since parameter format and fallback behavior, setting expectations.

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

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

Description adds value beyond annotations: it discloses scoping by identifier, persistent vs. temporary (24-hour) storage for anonymous sessions, and reinforces idempotent, non-destructive nature. Annotations already indicate idempotentHint=true and destructiveHint=false, so description complements rather than contradicts.

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

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

The description is a single well-structured paragraph, front-loaded with the main purpose. It includes examples, usage guidelines, and behavioral details without unnecessary words. Minor room for compression but still 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?

For a simple two-parameter write tool with no output schema, the description covers purpose, when to use, behavioral traits, and pairing with siblings. It does not describe return value or error cases, but these are not critical given the tool's simplicity and annotations.

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

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

Schema has 100% coverage with descriptive parameter examples. The description explains key-value pair storage and gives examples, but does not add substantial new meaning beyond the schema's descriptions. Baseline of 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, gives concrete examples (resolved ticker, target address, user preference), and distinguishes from sibling tools recall and forget by naming them explicitly.

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

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

Explicitly advises when to use ('when you discover something worth carrying forward'), contrasts with sibling tools ('Pair with recall to retrieve later, forget to delete'), and clarifies context (scoped by identifier, persistence differences).

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals important behavior: it returns specific fields per type (ticker/CIK/company_name for companies; RxCUI/ingredient/brand for drugs), includes citation URIs, auto-disambiguates input, and cascades through multiple lookup endpoints. This adds substantial context that annotations alone do not provide, and there is 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 moderately long but dense with practical information. It opens with user-phrase examples, gives a clear use-FIRST directive, and then breaks down supported types succinctly. All sentences contribute value, though the wall-of-text formatting (no bullet points or sections) slightly reduces 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?

Despite having no output schema, the description explicitly lists the return fields for both entity types, the accepted input formats, the underlying data sources (SEC EDGAR, RxNorm), and the internal cascading behavior. It also explains the auto-disambiguation, making the tool's behavior predictable and complete for an agent. This is a well-rounded, self-sufficient description.

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

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

The schema already provides full coverage of both parameters, so baseline is 3. The description adds meaningful nuance: it explains that 'value' accepts ticker, CIK, or company name for companies (with auto-disambiguation) and brand or generic names for drugs. It also gives examples like 'AAPL', '0000320193', and 'ozempic', which helps the agent construct valid calls.

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: resolving a user-spoken name to the canonical/official identifier required by other tools. It gives concrete examples ('What's the ticker for...', 'find the CIK for...') and distinguishes its scope by supporting 'company' and 'drug' entity types. The phrase 'use FIRST whenever you have a name but need an ID' further cements its role and differentiates it from sibling tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear invocation trigger. It also notes that the tool replaces 2-3 manual lookups internally. It does not explicitly list when not to use it or name alternative tools, but the guidance is sufficient for most agent decision-making.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds behavioral detail: it probes each entity, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density. 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?

Two sentences, front-loaded with the main purpose and key differentiators. No wasted words, each sentence adds clear 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?

No output schema, but the description lists all key return fields (score, confidence, signal density per entity) and input constraints (2-8 entities). Also mentions optional parameters like models and apiKey in context. Covers all necessary information for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting the first entity is treated as the subject for narrative, which provides usage context beyond the schema. Also implies the purpose of each parameter without repeating schema definitions.

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

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

The description uses a specific verb ("Compare AI visibility") and clearly identifies the resource (multiple entities). It distinguishes from siblings by mentioning it probes each entity with ai_visibility_check and produces a ranked list, which is a clear differentiator from the single-check sibling.

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

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

Explicitly states it is useful for competitive AI-marketing audits. Implies use over single-check alternative (ai_visibility_check) but does not explicitly state when not to use or provide concrete alternatives among 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals behavioral details: fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement may take 5-30s with sources_failed listing timeouts. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the core value proposition. Although fairly long, every sentence adds value, covering usage, return format, and limitations. Minor deduction for density.

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

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

Given no output schema, the description fully explains return fields (summary block, advisories, versions) and limitations (timing, NPM-only). It covers all essential context for effective tool selection and invocation.

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

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

Schema coverage is 100% for both parameters. The description adds context about defaults and scoped packages but does not significantly enhance parameter understanding beyond the 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 explicitly states it's a composite check for deciding whether to add an npm package, covering license, advisories, bundle size, and tree-shake support. It clearly distinguishes from siblings like 'scan_competitor_ai_presence' by specifying the NPM ecosystem 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?

Provides explicit when-to-use guidance: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also specifies NPM-only and recommends deps.dev directly for other ecosystems, offering clear 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?

Discloses technical details beyond annotations: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation and flag), and return of offsets for verification. Annotations already declare readOnlyHint, idempotentHint, destructiveHint.

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

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

Well-structured: starts with purpose, then usage, then technical details. Dense but every sentence adds value, though could be slightly more concise.

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

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

Even without an output schema, the description explains return format (passages with offsets and similarity scores) and edge cases (truncation, flag). 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 good descriptions. The description adds value with examples for query parameter and default/range for limit, plus max length note for text. No contradictions.

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 does semantic search inside a fetched record, specifying use cases (SEC 10-K, article, long tool result) and return type (passages with offsets and similarity scores). It distinguishes from sibling ask_pipeworx_grounded by describing the pairing.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt' and provides a 'Pairs with' recommendation to ask_pipeworx_grounded, guiding the agent to choose this tool over alternatives.

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

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

Annotations indicate it's a write operation (readOnlyHint=false) and idempotent. The description adds behavioral details: requires OAuth, sms cap, webhook auto-disable, and return of subscription id. No contradictions.

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

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

The description is well-structured with front-loaded purpose and clear sections. It is somewhat lengthy but every sentence adds value; minor redundancy could be trimmed.

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

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

Given the tool's complexity (multiple event types, delivery channels, auth requirements), the description covers prerequisites, examples, constraints, and return value. Without an output schema, it adequately describes what the agent can expect.

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

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

The description enriches the schema with detailed examples and constraints for each type and delivery option (e.g., phone verification, sms cap, webhook signing). Schema coverage is 100%, but the description adds critical context beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID, distinguishing it from related tools like list_subscriptions and unsubscribe.

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

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

The description specifies when to use (live-data monitoring), prerequisites (Pipeworx OAuth account), and delivery options with constraints. It lacks explicit 'when not to use' guidance but provides sufficient context for correct selection.

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

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

Annotations already indicate idempotent, non-destructive reads. The description adds value by detailing that it returns examples drawn from thousands of tools, and that omitting the argument gives a cross-category spread. No contradictions.

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

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

The description is front-loaded with the purpose and key usage phrases. It lists many categories, which is informative. While somewhat long, each sentence adds value, and the structure is clear.

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

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

Given the tool's role as an onboarding entry point with one optional parameter and no output schema, the description is fully complete. It explains what it returns, when to use it, and how to use it, even referencing other meta-tools.

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

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

Schema coverage is 100% with a single optional parameter. The description enriches meaning by listing concrete categories (finance, pharma, etc.) and explaining the effect of omission vs. inclusion, going beyond the schema description.

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

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

The description provides multiple clear phrasings of the tool's purpose (e.g., 'what can I ask Pipeworx?', 'getting started'), states it returns category-bucketed example questions with exact tool calls, and explicitly distinguishes it from sibling tools by marking it as the onboarding entry point.

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

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

The description explicitly advises to use this tool FIRST when unsure of Pipeworx capabilities, and explains when to pass a topic vs. omit it for full spread. It also mentions learning how to call meta-tools, providing clear usage guidance.

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

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

Discloses key behavioral traits beyond annotations: the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. This adds context that annotations do not cover, with no contradiction.

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

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

Two succinct sentences: first states the action, second adds ownership and deactivation behavior. Every sentence serves a purpose without redundancy.

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

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

For a single-parameter tool with no output schema, the description covers action, usage constraint, behavioral effect, and related tool reference ('recent_alerts'). No gaps remain.

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

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

The parameter 'id' is fully described in the schema. The description adds valuable context by specifying 'by id' and noting that the id is returned by 'subscribe', enhancing understanding beyond the schema alone.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also specifies the behavioral nuance of deactivation rather than 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?

Provides explicit ownership constraint: 'you can only cancel your own subscriptions.' This guides the agent on when to use the tool and implicitly when not to, though it does not explicitly mention alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details such as the two processing paths, the return fields (verdict, actual value with citation, reasoning), and that it replaces multiple calls. It could mention potential limitations like handling of unsupported claims.

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

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

The description is long but front-loads the key purpose with examples and is packed with useful information. Every sentence adds value, though it could be slightly trimmed without losing essential content.

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

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

Given the tool complexity (two pathways, multiple return fields), the description is complete. It covers the main behavioral aspects and lists the return fields even though there is no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds nuance about tolerance_pct overriding default tolerance, and notes the default is implied by wording and capped at 5. This extra context justifies a 4.

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

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

The description starts with specific trigger phrases like "Is it true that…" and explicitly states it's for claim verification against authoritative sources. It distinguishes itself from siblings by mentioning it replaces 4–6 sequential calls.

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

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

The description explicitly says when to use: "whenever the agent needs to check whether something a user said is factually correct." It also differentiates between company-financial claims and other claims, but does not provide explicit exclusions or when not to use.

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