Rss2json

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

Annotations already mark read-only and idempotent; the description adds key behavioral context: default model is free, Anthropic probing requires a BYO key and incurs direct costs. This clarifies external service usage beyond the annotation hints.

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

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

Four sentences, front-loaded with purpose, then default behavior, output shape, and use cases. No filler; every sentence contributes.

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 specifies the return structure (per-model fields plus combined view) and practical use cases. Combined with rich annotations, it gives an agent enough to invoke the tool correctly.

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

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

Input schema has 100% parameter documentation, so the description doesn't need to re-explain. It does add helpful hints about the default model and key requirement, but these are also present in the schema properties. Thus baseline 3 is appropriate.

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

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

The description opens with 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' which is a specific verb-action plus resource and output. It clearly distinguishes this from sibling tools by focusing on cross-model visibility scoring.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that indicate when to apply it. Does not mention alternatives or exclusions, but the context is clear enough for selection.

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

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

It discloses behavioral traits beyond the annotations: it delegates to a large ecosystem of tools, auto-fills arguments, and returns structured answers with stable citation URIs. The annotations already establish a read-only, idempotent, open-world profile, and the description does not contradict them. It does not discuss latency or failure modes, but those are less critical given the safe annotation profile.

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

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

The description is well front-loaded with the most important instruction ('prefer over web search'), followed by scope, mechanism, triggers, and examples—most sentences earn their place. However, it is long, and the final sentence is visibly truncated ('should ...'), which makes the ending feel incomplete and slightly undermines the overall 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?

For a single-parameter read-only router with rich annotations, the description covers the main invocation path well: what it does, when to use it, examples, and the citation-bearing return format. The notable gaps are the lack of clear differentiation from ask_pipeworx_beta and ask_pipeworx_grounded, and the unfinished caveat about broad/multi-part questions, which also leaves ambiguity around the `deep_research` sibling.

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

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

The schema already documents the single `question` parameter and its aliases with 100% coverage, so the baseline is a 3. The description adds value by specifying the kinds of questions that belong in that parameter and providing concrete examples, which helps an agent phrase a query. It does not add format or length constraints, but those are unnecessary for a free-text natural-language parameter.

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

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

The description clearly identifies ask_pipeworx as a router/orchestrator: it routes a natural-language question to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns answers with stable pipeworx:// citation URIs. It is specific and not a tautology, and 'prefer over web search' sets a clear main use. However, it does not explicitly distinguish itself from sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, so it stops short of full sibling 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?

The description gives explicit use conditions: prefer over web search for structured or factual data, trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', and 'current', plus six concrete examples. It tells the agent to start here for most questions. The main gap is that the final caveat about broad/multi-part questions is truncated ('should ...'), and it does not explicitly mention the beta/grounded siblings as 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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's job is lighter. It adds genuinely useful dynamic behavior: candidate routing improvements go live whenever under test, the last was retired, and "Falls back to nothing — this IS a full working router" disambiguates the beta status. It does not disclose rate limits, latency overhead of beta testing, or failure behavior when a candidate misroutes.

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

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

Four sentences with the identity and current parity front-loaded before usage guidance; nothing is wasted. The precise retire date ("2026-07-26") and the parity claim repeated in sentences 1, 2, and 4 are slightly redundant and 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?

For a complex 6-parameter router with no output schema, the description covers identity, current behavior, when to use it, and the A/B evaluation context. Defaulting the response shape to "same response shape" as ask_pipeworx is reasonable but forces the agent to resolve a sibling's contract. The experimental edge and current parity are explained well enough to call the tool safely.

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 question and its aliases are fully self-documented; the description adds no parameter-level meaning beyond the phrase "same arguments" which only confirms parity with ask_pipeworx. Baseline 3 applies because the schema does the heavy lifting and the description does not need to compensate.

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

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

The description clearly states what the tool is: "Beta version of ask_pipeworx: identical universal router (same 5,798 tools, same arguments, same response shape)", giving a specific resource scope and distinguishing it from the stable sibling ask_pipeworx via its experimental role. However, the core action is carried by the jargon term "universal router" and reference to ask_pipeworx rather than a plain verb, so it is clear but slightly indirect.

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 an explicit selection condition: "Use it exactly like ask_pipeworx when you want the newest routing", and names the stable alternative against which results are compared. It also cautions that no candidate is active right now, so current behavior matches the stable router. It does not explicitly state when-not-to-use or mention the ask_pipeworx_grounded sibling, so it stops short of a 5.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses important behavioral traits: it may refuse to answer rather than fabricate, returns verbatim evidence, costs an extra LLM call, and enumerates all refusal_reason values. This goes well beyond what annotations provide and prepares the agent for failure modes. There is no contradiction with the readOnlyHint or idempotentHint.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return shape, refusal semantics, high-stakes use cases, and cost tradeoff. It front-loads the core identity ('Hallucination-resistant answer mode') and structures the rest as a natural flow from behavior to 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?

For a tool with a single question parameter, no output schema, and rich annotations, the description is fully self-sufficient. It covers return values, refusal behavior, use cases, cost tradeoff, and the alternative tool. There is nothing an agent needs to call this tool correctly that is missing.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question.' The description itself adds no parameter-specific meaning, but the schema already carries the full burden, so baseline 3 is appropriate. No additional param semantics are needed here.

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

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

The description states a specific function: a hallucination-resistant answer mode that routes through the same underlying retrieval as ask_pipeworx and extracts answers only from fetched tool results. It clearly distinguishes itself from siblings like ask_pipeworx by emphasizing grounded extraction, evidence quoting, and explicit refusals. The verb 'EXTRACTS' plus the defined return/refusal shapes make the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains. It also provides a clear when-not-to-use instruction: 'prefer ask_pipeworx for casual lookups,' plus a cost rationale. This is model guidance for routing between close siblings.

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

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

Annotations already indicate read-only and non-destructive, but the description goes far beyond by detailing resolver confidence levels, low-confidence short-circuit statuses, closed-market behavior, wide-spread tradeability warnings, and cancellation-rule parsing. It even warns about 'recurring pure-rules loss' from void settlements, providing critical risk disclosure 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 lengthy but well-organized with uppercase section labels (CLASSIFIERS, RESOLVER CONTRACT, SAFETY) that enable easy scanning. It is front-loaded with a clear purpose sentence, and while the volume of detail is high, each sentence adds substantive behavioral or safety context rather than filler.

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

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

For a tool with no output schema, the description thoroughly documents response shapes: result.market fields, result.analysis, result.evidence, market_match_score/alternatives, parent_event structure, news fallback fields, and status values. It covers edge cases like wide spreads and cancellation rules, making it 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?

The schema already covers all three parameters (market, depth, include_raw) with complete descriptions. The description restates the market input types but adds no new parameter-level details beyond the schema, so the baseline of 3 applies.

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

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

The description states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb+resource that clearly distinguishes it from general tools like ask_pipeworx or deep_research. Concrete use cases ('should I bet on X', 'is there edge in Z') further sharpen the purpose.

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

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

It explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which provides clear contextual usage. However, it does not name alternative tools or explicitly state when not to use it, so it misses the explicit when-not/alternative guidance of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), exact fields pulled (revenue, net income, cash, long-term debt), sorting behavior, and output details (paired data + citation URIs). This substantially exceeds annotation coverage and gives the agent a clear model of tool behavior.

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

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

While long, every sentence carries meaningful information: trigger phrases, the parallel-call advantage, type-specific data sources, sorting, and output format. The structure front-loads the primary purpose and usage, then details data behavior. No redundant or filler content is present.

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

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

Given the tool's complexity (two entity types, 2–5 items, multiple data dimensions, no output schema), the description is remarkably complete. It covers inputs, data sources, fiscal-year edge cases, sorting, and output format, leaving no major ambiguity for an agent selecting or invoking 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 already covers 100% of parameter meaning, so baseline is 3. The description adds value by explaining the semantics of each type: for company it pulls 10-K financials, for drug it pulls adverse-event and trial counts. It also contextualizes the values parameter with examples (tickers vs drug names) and clarifies that 'largest'/'most' maps to the sort order, going beyond 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 identifies the tool as performing side-by-side comparisons of 2–5 companies or drugs, with specific trigger phrases ('Compare X and Y', 'X vs Y'). It distinguishes itself from siblings by explicitly noting it should be preferred over sequential single-pack lookups and that it replaces 8–15 lookups, making the purpose unique and unmistakable.

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

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

The description provides explicit guidance on when to use the tool (trigger phrases, comparison intent) and when not to (sequential single-pack lookups). It also gives type-specific contextual instructions, such as handling off-calendar fiscal years for companies, and notes that results are sorted by primary metric, which helps the user interpret output correctly.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial disclosure beyond them: the findings-packet shape (verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation), a 'never invented' gaps[] guarantee, contradictions[] behavior for standard/thorough, semantic excerpting (not head-truncated), latency bounds (15-60s, ~90s for thorough), and paid-tier restrictions. No contradiction with the annotations.

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

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

The description front-loads the critical account caveat and every sentence carries information, but at roughly 300 words it is overlong, and the passage 'Main bottleneck (one LLM call, not many)...' reads like a corrupted fragment that duplicates what the schema's depth enum description already says. Depth-tier facts are scattered across three separate spots, weakening the 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?

With no output schema, the description must carry the return contract, and it does thoroughly: findings-packet fields, citation fetchability guarantee, gaps[], contradictions[], excerpting behavior, tier differences, and expected latency. For a tool this complex (multi-tier depth, permissions, non-trivial return shape), nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 100%, so the schema documents question and depth well. The description adds value on top: example question phrasings, the paid-plan consequence of depth='thorough', and per-tier behavioral details (gap-recovery hop, contradiction scan) that reinforce the enum semantics rather than merely repeating them.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, and explicitly differentiates itself with 'this is NOT open-web search.' It also names the closest sibling (ask_pipeworx) as the single-lookup alternative, so an agent can select it without opening any schema.

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

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

Gives explicit routing rules: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It defines the ideal use case ('best for broad/multi-part questions over structured data') with two concrete example questions, leaving no ambiguity about when this tool wins over its siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail about the return value: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and promises that results are 'ready to call directly, no second schema lookup needed.' This adds useful context beyond the annotations.

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

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

The description is four sentences, front-loaded with the core action ('Find tools by describing the data or task'), followed by usage context, return details, and a direct instruction ('Call this FIRST'). No filler—every sentence adds value, and the long list of domains is compactly presented.

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 meta-tool with no output schema, the description fully covers its purpose, when to use it, and what the response contains ('names, descriptions, and full input schemas'). It also provides explicit ordering guidance ('Call this FIRST'), making it complete for an agent to invoke correctly.

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

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

The input schema has 100% coverage with descriptions for all 6 parameters, including aliases and limit. The description's mention of 'top-N' and 'describing the data or task' aligns with the schema but doesn't add new parameter-level semantics. Baseline 3 is appropriate since the schema already handles 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 opens with 'Find tools by describing the data or task', clearly identifying the tool's purpose as a discovery/meta-tool. It explicitly lists example domains and distinguishes itself from siblings by focusing on browsing/searching available tools, not performing domain-specific analysis.

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

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

The description states 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides explicit when-to-use guidance and implies that when you already know a specific tool, you should call it directly.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond. It discloses the parallel fan-out across sources, the soft-fail behavior (USPTO PatentsView API sunset), the meaning of empty sections (sources_used/sources_failed), and the resolved:false response for private companies. This is exemplary behavioral disclosure that eliminates surprise for the agent.

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 intentionally packed with essential details for a highly complex tool. It leads with usage examples and purpose, then systematically lists data sources and return sections. While verbose, there is no filler; every clause contributes to operational understanding. It sacrifices brevity for completeness, which is appropriate here, though it could be tighter.

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

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

Given there is no output schema, the description must explain every return section, and it does: recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, plus sources_used/sources_failed. It also covers edge cases (private companies, FDA sections with no data, USPTO sunset) and includes example URIs. For a tool this complex, the description leaves no gap that would prevent correct invocation or interpretation.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying that 'type' accepts "company" or "ticker" interchangeably and that 'value' can be a ticker, zero-padded CIK, or company name, and that names resolve via EDGAR company-name match. It also explains the private-company edge case (resolved:false with notes). This goes beyond the schema's enum descriptions, justifying a 4.

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

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

The description opens with explicit user intents ("Tell me about X" / "research Acme") and states its core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific sources (SEC EDGAR, XBRL, USPTO, etc.) and clearly differentiates itself from chaining single-pack lookups. This is a precise, resource-bound definition that leaves no ambiguity about what the tool does.

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

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

It provides direct usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted input forms (ticker, CIK, name) and expected behavior for private companies. The description conditions the tool's use on the user's request type, making it easy for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that both RSS and Atom formats are supported, which is useful, but discloses no further behavioral traits like rate limits or error handling.

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

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

The description is a single, focused sentence front-loading the action and output format. Every word earns its place with 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?

The tool is simple, and with an output schema present and strong annotations, the description is sufficient. It states the feed types supported and output format, covering the core context without needing extra detail.

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 67% (count and api_key have descriptions, rss_url does not). The tool description does not add any parameter-level meaning beyond what the schema already provides, but the required rss_url is self-explanatory.

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 'Fetch RSS/Atom feed as JSON' clearly states the verb (fetch), the resource (RSS/Atom feed), and the output format (JSON). It distinguishes from all sibling tools, none of which mention feed handling.

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

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

The description implies usage for retrieving RSS/Atom feeds, but provides no explicit when-to-use or when-not-to-use guidance, and names no alternatives. The context is clear but not elaborated.

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 destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds usage context but no additional behavioral traits like deletion permanence or effects on missing keys, so it's sufficient but not extra-rich.

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

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

Three short sentences: purpose, when to use, and related tools. No fluff, front-loaded with the action, and 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?

For a simple one-parameter tool with annotations and full schema coverage, the description fully covers the 'why' (usage scenarios) and the 'what' (delete by key). No output schema needed, and idempotentHint covers missing-key behavior implicitly. Complete for its complexity.

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

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

Schema covers 100% of the one parameter (key) with a clear description. The description does not add any extra parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The first sentence, 'Delete a previously stored memory by key,' uses a specific verb and resource, clearly distinguishing it from siblings like remember and recall. No ambiguity about the 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?

Explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with remember and recall, providing clear alternative 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?

The description discloses key behavioral traits beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also notes the output is a single text blob. Given the read-only, idempotent annotations, this additional process detail is valuable. It does not mention potential network errors or rate limits, but that is a minor gap for a read-only 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 three well-structured sentences: purpose, process, and use cases. It is front-loaded with the core function, every sentence adds value, and there is no redundant text. It is appropriately sized for a tool with two parameters and a clear output.

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

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

The description covers the tool's purpose, process, output format, and common use cases. Since there is no output schema, the mention of 'a single text blob ready to drop at site-root/llms.txt' is helpful. It doesn't address edge cases like invalid URLs or fetch failures, but for a simple read-only tool with robust annotations, the description is largely complete.

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

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

The input schema has 100% coverage, with url and max_links already described clearly. The description adds little beyond the schema: it mentions 'any URL' and 'key links' but doesn't elaborate on parameter defaults or constraints. Since the schema fully covers the parameters, the baseline of 3 is appropriate; the description doesn't provide extra nuance.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the verb (generate), resource (llms.txt), and scope (any URL), and details the process (fetches, extracts, emits). This distinguishes it from sibling tools like ai_visibility_check or deep_research, as its focus is on producing a specific file format.

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 several use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool, though it doesn't mention exclusions or alternative tools. The guidance is helpful but not as explicit as a direct comparison to siblings.

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

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

Annotations already declare read-only and idempotent behavior. The description adds value by disclosing the return field set and that the operation is scoped to the caller's subscriptions, including the implicit default of active-only. This goes beyond the annotation coverage.

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

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

Two sentences: the first states purpose and output, the second gives usage guidance. No filler or redundancy, every word contributes to understanding.

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 list tool with one optional parameter, the description plus schema and annotations provide a complete picture. The return fields are listed, usage guidance is given, and the parameter is documented. No output schema exists, so no omission there.

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 only parameter include_inactive is fully documented in the schema. The description does not add additional parameter semantics, so the baseline 3 is appropriate.

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

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

The description opens with 'List the caller's active subscriptions,' which is a specific verb+resource+scope statement. It also lists the exact fields returned, making the tool's purpose unambiguous and distinguishing it from siblings like subscribe and unsubscribe.

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

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

Provides clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies appropriate use cases and contrasts with subscribe/unsubscribe actions, though it does not explicitly name 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 provide no useful safety hints (all booleans false), so the description carries the burden. It discloses the claim_token workflow (returns a token for later lookup), rate limiting (5/day/identifier), quota exemption (free, doesn't count against tool-call quota), and that feedback is read daily. This is substantive behavioral context beyond the annotations.

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

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

The description is a single dense paragraph, but every sentence earns its place: purpose, usage, exclusions, token workflow, rate limits, and quota impact. It is appropriately sized for the tool's complexity, though better formatting (e.g., bullet points) could improve scannability.

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

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

For a tool with 4 optional parameters, a nested object, no output schema, and minimal annotations, the description is remarkably complete. It covers purpose, when to use, when not to use, input guidance, return behavior (claim_token), rate limits, quota, and processing timeline, fully equipping an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces claim_token usage and mentions context (tools/packs) but does not add new semantic meaning beyond what the schema already provides. The enum values are already fully described in the schema.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly ties the tool to feedback about Pipeworx tools, distinguishing it from sibling tools like ask_pipeworx or discover_tools that are for queries and 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?

The description gives explicit when-to-use cases: bug (wrong/stale data), feature/data_gap (wish existed), and praise. It also states when not to use it (tools from other MCP servers) and directs the user to file with that server instead, naming the alternative. Guidance about using Pipeworx tool names and avoiding end-user prompts further clarifies usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds valuable non-obvious behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs the agent about data provenance, privacy, aggregation level, and caching – details not present in annotations and highly relevant for interpretation.

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

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

The description is well-structured with a clear opening sentence, a sentence describing returns, bullet-point use cases, and a final caveat sentence about caching and PII. It is longer than strictly necessary but every sentence carries information. The 'Useful for' bullets are slightly redundant (the second and third both relate to alignment) but overall the structure is logical 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?

For a simple tool with one optional parameter and no output schema, the description is thorough. It explains what the tool returns (top tools, top packs, total call volume), the window options and their interpretation, the timestamp-based use cases, and the caching/PII properties. This is enough for an agent to decide when to call it and what to expect from the result.

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

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

The schema description for the single 'window' parameter is fully self-sufficient: it specifies the enum values (24h, 7d, 30d), the default, and explains that shorter windows show hot items and longer windows show steady-state demand. The tool description merely restates '24h, 7d, or 30d' without adding new meaning. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description opens with a clear summary of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It then specifies the exact outputs: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This is a specific verb+resource description that clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx, which focus on querying and discovery rather than aggregate usage trends.

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 three concrete 'Useful for' scenarios: discovering hot data sources for current events, confirming a popular tool is canonical before asking a question, and checking alignment with common agent needs. It also explains that shorter windows surface hot items while longer windows show steady-state demand. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a full 5.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds substantial behavioral context: fill check with live CLOB depth, partition filter for placeholders, semantic similarity threshold, and the condition that realizable_edge_pp ≤ 0 means not to trade. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every section adds necessary detail for complex behavior. It is somewhat dense but front-loaded with the core purpose. Not excessively verbose relative to the tool's complexity.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It specifies the response structure (opportunities[], partition_check, fill check fields) and covers edge cases like low-similarity pairs and placeholder filters. Given the tool's complexity, the description is remarkably 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 descriptions for both parameters. The tool description goes far beyond the schema by providing concrete examples (e.g., 'fed-decision-may-2026'), explaining mode semantics, and detailing how each parameter changes the scan behavior. This adds significant meaning beyond the input 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 specifies the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes between event and topic modes and alludes to sibling tools like polymarket_fill_risk, separating it from other Polymarket-related 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?

Explicit guidance is provided: 'Call with NO args' for trending scan, 'event' for single-market, 'topic' for cross-event. It recommends 'event' for specific markets and names an alternative for custom sizing. This gives clear when-to-use and when-not-to-use 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?

With annotations already indicating readOnly/openWorld/idempotent, the description goes well beyond by disclosing model families, slippage assumptions, edge netting, caching at KV level for 1h, placeholder-slug filters, and the 24h-move warning. It also explains why Fed bets are excluded (unreliable signal), providing deep behavioral context without contradicting annotations.

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

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

The description is lengthy and dense, but every sentence carries substantive technical detail. It is front-loaded with a clear purpose, but the single-paragraph structure could be improved with segmentation or bullets. Still, it is appropriately sized for a complex tool with 9 parameters and no output schema, earning a 4.

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

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

Despite no output schema, the description fully specifies the response structure (by_segment, fed_candidates, _diagnostics), explains segment logic, and describes diagnostics like funnel counters and filter_skips. It also covers edge fields with units (edge_pp_net, kelly_fraction_half capped at 0.25). This is a complete context for callers.

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 meaning by explaining how parameters map to segments (e.g., min_partition_leg_kelly applies to per-leg Kelly inside top_legs, not parent-level) and provides rationale ('slippage_pp... Polymarket has zero trading fees... but bid/ask typically eats 20-50bp'). This enhances the schema's descriptions, justifying 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 clearly states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes from siblings by emphasizing its role in daily bet discovery and detailing three unique response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which differentiates it from tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description gives clear usage context ('Built for "what should I bet on today"') and explicitly describes how knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly adjust tradeability, telling agents when to tighten or relax filters. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusions/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?

The description goes beyond the readOnlyHint annotation by disclosing critical behavioral details: snapshots are written on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net (net of slippage), and expired opportunities reflect closed/resolved/arbed-away markets. These traits are not visible in annotations or schema, making the description highly transparent.

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

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

Although long, the description is front-loaded with the core question, then efficiently structures args, response fields, and limitations. Every sentence contributes essential information: response formats (tracked, expired, snapshot_dates), interpretation guides (median lifespan as competition clock), and data caveats. No wasted words.

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

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

With no output schema, the description fully specifies the return structure: tracked[], expired[], and snapshot_dates[], including each subfield's meaning. It also covers data provenance, limitations (TTL, daily closes), and edge cases (snapshot gaps). This makes the tool understandable and usable without additional documentation.

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 descriptions already fully cover both parameters (days and window) with defaults and constraints. The description adds minor context (e.g., 'snapshot family') but does not introduce meaning beyond what the schema provides. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's unique function: "Edge persistence and decay telemetry built from daily polymarket_edges snapshots." It answers a specific question ("how long has this edge existed and is it shrinking?") and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trend and decay rather than current edges.

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

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

The description provides clear context for when to use the tool: when you need to know if an edge is fresh or old and whether it is decaying. It implies the trade-off with fresh vs. stale edges but does not explicitly discuss alternatives or when-not-to-use. The context is clear enough to guide 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 declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail: ladder walking, return metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), mode-specific semantics (basket sums vs single-market), and risk naming (forced_directional_risk, thin_legs). This exceeds what annotations convey and gives a rich picture of runtime behavior. No contradictions with annotations.

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

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

The description is long but every major clause earns its place. It front-loads a one-sentence summary, then clearly sections SINGLE-MARKET vs BASKET, enumerates return fields, and ends with concrete usage guidance. The structure mirrors the tool's dual-mode nature, making dense information navigable. No filler or repetition exists.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is fully self-sufficient. It explains inputs, outputs per mode, default values, clamps, risk indicators, and edge cases (partial fills, forced directional risk). It also places the tool in the broader workflow of arbitrage and edge trading. Nothing critical is missing.

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

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

Though the schema covers 100% of parameters, the description adds critical interpretive meaning: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode; side defaults are clarified and basket auto side explained. This is exactly the kind of parameter deep-dive that the schema alone doesn't provide.

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, actionable definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and explicitly names those tools as and-candidates for pre-trade validation.

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

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

Usage guidance is explicit and directive: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills create unhedged directional risk), giving clear when-to-use and why-to-use context that differentiates it from 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 mark the tool as readonly, idempotent, and non-destructive, and the description adds substantial behavior beyond that: compatibility codes, fee-schedule limitations, temporal alignment null semantics, skipped-leg counters, and the keyword-matching caveat behind returned pairs. This is exemplary disclosure for a complex financial comparison 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 long, but it is well-organized with clear labels for modes, response, safety fields, and disclosures. Some points are repeated across the mode and flag explanations, but the density is largely justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, compatibility fields, temporal alignment structure, fees note, and skipped comparison counters. It also warns about interpretability pitfalls and matching limitations, making it complete for correct invocation and result interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining how the topic parameter maps to pre-mapped macros and how kalshi_event_ticker and polymarket_event_slug override those mappings while still running the same matcher. This clarifies the relationship between the parameters beyond the schema's individual 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 identifies a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific resource and analytical function. It does not explicitly contrast itself with siblings like polymarket_arbitrage, but the core purpose is unambiguous.

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

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

The description clearly explains the two operating modes (topic shortcuts vs explicit pairings) and when each is appropriate, and it cautions that pre-mapped topics are not always tradeable. It does not explicitly name alternatives to this tool, but the internal usage guidance is strong and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds important behavioral context about scoping ('Scoped to your identifier') and the omitted-key behavior, going beyond the annotations.

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

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

Two sentences, front-loaded with the primary action, no filler. Every phrase adds value, from the dual behavior to the pairing with sibling tools.

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 1-param tool with robust annotations, this is complete: it covers both invocation modes, scoping, and pairing with siblings. No output schema is needed given the clarity of the return behavior.

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

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

The schema covers 100% of the single 'key' parameter, so the baseline is 3. The description enriches it with illustrative examples of what values might be stored (target ticker, address, research notes), adding meaning beyond the schema's terse 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 opens with a specific action — 'Retrieve a value previously saved via remember, or list all saved keys' — clearly identifying the resource and the two invocation modes. It distinguishes from siblings by explicitly naming remember and forget as paired tools.

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

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

The description gives an explicit use case: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also states the relationship with remember/forget, implying when not to use this tool.

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

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

The description discloses a mutating behavior (mark_read:true flags returned events read and changes future call results), but the annotations declare readOnlyHint=true and idempotentHint=true. This is a direct contradiction, severely undermining the trustworthiness of the description.

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

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

The description is three sentences, front-loaded with the main action, and contains no filler. There is slight redundancy between 'pull fired events' and 'returns the most recent alerts,' but every sentence still provides useful 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 full schema coverage and annotations, the description covers return payload fields, filtering, mark_read semantics, and the alternative HTTP endpoint. The lack of an output schema is mitigated by explicit return-field details. However, the readOnly contradiction creates a trust gap.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond it: an example filter value ('sec_8k'), clarification of mark_read's effect ('only shows newer ones'), and ISO timestamp syntax. This enriches the structured parameter 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: pulling fired events from a subscription feed, with filtering and mark_read behavior. It is specific about the resource and returns, but it does not explicitly distinguish itself from the sibling 'feed' tool.

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

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

The description gives practical usage context: mentions polling works fine, notes the same feed is available via HTTP for scripts/dashboards, and explains filtering options. However, it does not state explicit when-not-to-use or alternatives relative to sibling tools.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the fan-out architecture to SEC EDGAR, GDELT→GNews fallback, and the PatentsView API sunset condition. It also explains the output shape (changes[] grouped by source, total_changes, citation URIs), which is valuable behavioral context.

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

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

The description is dense but every sentence carries meaningful information: use cases, source routing, parameter format, output structure, and an alternative tool reference. It is front-loaded with the most important intent signals and avoids filler or redundancy.

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

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

Given there is no output schema, the description adequately covers the return format (changes[] grouped by source, total_changes count, citation URIs). It also covers the entity type limitation, `since` parameter semantics, source failure behavior, and when to choose a sibling tool. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and all three parameters have descriptions, so the baseline is 3. The description adds extra value by giving concrete usage recommendations (e.g., 'Use "30d" or "1m" for typical monitoring') and clarifying that `value` accepts either ticker or zero-padded CIK, which complements 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 defines the tool as a change feed for a company over a recent window, listing concrete sources and output format. It distinguishes itself from entity_profile by noting that the profile tool should be used for static profiles. The trigger phrases at the start make the purpose immediately recognizable.

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 states when to use the tool (recent-change queries like 'What's new' and 'updates on Acme') and provides a direct alternative ('Use entity_profile instead when you want the static profile'). The fallback behavior between news sources and the soft-failure of USPTO also helps set 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?

Adds significant context beyond annotations: 'scoped by your identifier', 'Authenticated users get persistent memory', 'anonymous sessions retain memory for 24 hours'. These details are not inferable from readOnlyHint, idempotentHint, or 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?

Three sentences, each earning its place: the first states purpose, the second gives usage triggers, the third details storage semantics and companion tools. Efficient, 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?

For a tool with two simple parameters and no output schema, the description fully covers purpose, usage, persistence behavior, and relationships to sibling tools. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description provides examples (e.g., 'resolved ticker', 'user preference') and reiterates key-value structure, but these largely mirror the schema's examples ('subject_property', 'target_ticker'). Minimal added nuance beyond schema.

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

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

The description uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly defining the tool's function. It distinguishes from siblings by explicitly pairing with recall and forget, resolving any ambiguity.

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 when you discover something worth carrying forward' with concrete examples. Also mentions companion tools (recall, forget), making the decision context clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses graceful degradation when GLEIF/OpenFIGI are unavailable, the assert-nothing-and-return-figi_candidates behavior on ambiguous matches, explicit unresolved fields, source-labelled identifiers, and internal multi-endpoint cascading. This is exactly the behavioral context an agent needs.

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

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

The content is dense and relevant, but it is delivered as one long run-on paragraph with many nested parenthetical clauses, which is harder for an agent to parse than a bulleted structure. It is front-loaded with examples and the trigger condition, but could be tightened and 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?

With no output schema, the description carries the burden of explaining return values, and it does: the company branch names CIK/ticker/company_name/LEI/FIGI, the drug branch names RxCUI/ingredient/brand/citation, and it documents ambiguity, unresolved identifiers, and degradation. Given the tool's complexity, nothing essential is missing.

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

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

Even though the schema already documents both parameters comprehensively (100% coverage), the description adds critical semantics: accepted input forms for company (ticker, CIK, ISIN, name), the ISIN-to-LEI mapping nuance, and the explicit caution to pass only the issuer name, not the full noun phrase. That materially reduces mis-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 opens with concrete user-phrase examples and then states a specific function: resolving a user-spoken name to the canonical identifiers that other tools need as input. This is a specific verb+resource and clearly positions the tool as the name-to-ID lookup layer relative to the sibling tools that consume those IDs.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving the agent a crisp trigger condition. It does not name alternatives or state explicit when-not cases (e.g., if an ID is already known, go elsewhere), so it misses the top bar by a small margin.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds behavioral context by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns metrics (score, confidence, signal density). This goes beyond the annotations and informs the agent of the internal process and output structure.

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, starts with the primary action, includes a concrete use-case example, and ends with the return format. Every sentence adds value; there is 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?

For a tool with no output schema, the description clearly states what is returned (ranked list with score, confidence, signal density) and explains the process (probes with ai_visibility_check, ranks). It also covers the competitive audit use case. It does not explicitly mention entity count limits or model selection behavior, but those are handled by the schema. Overall, enough for an agent to use correctly.

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

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

Schema description coverage is 100%, with each parameter (entities, models, _apiKey, context) having a clear description. The tool description itself does not repeat parameter details, but the schema already does the heavy lifting. Per the baseline, a score of 3 is appropriate because the description adds no additional parameter semantics beyond schema coverage.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by stating it probes with ai_visibility_check and ranks by score. The purpose is unmistakable.

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

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

The description provides a clear context: 'Useful for competitive AI-marketing audits' with an example query. It implies this is for multi-entity comparisons, but does not explicitly state exclusions or alternatives such as 'for a single entity, use ai_visibility_check.' The context is clear enough for an agent to decide, but lacks explicit when-not-to-use guidance.

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

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), it discloses fan-out behavior, potential 5-30s latency on first bundlephobia measurement, graceful partial failure, and the sources_failed field — valuable operational context that annotations do not provide.

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

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

The description is long but front-loaded with purpose, then usage, then output fields and caveats. Every sentence contributes necessary context, especially given no output schema.

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?

It enumerates the returned summary fields, per-advisory detail, links, and recent alternative versions despite no output schema. It also clarifies scope and edge cases, making the tool's behavior fully anticipatable.

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

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

Schema covers both parameters with full descriptions (100% coverage), so the description adds little parameter-specific meaning. It confirms defaulting to the latest version, but that is already in the schema.

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

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

The description names a specific composite action: checking whether to add an npm package to a project by aggregating deps.dev and bundlephobia data. It is clearly distinct from sibling research tools and explicitly scopes to the NPM ecosystem.

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

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

Explicit use cases are given ('is X safe / popular / small', 'what does adding lodash cost me'). It also names the alternative path (deps.dev:version directly) for non-NPM ecosystems, providing clear when-not 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?

Beyond the readOnly/openWorld annotations, the description discloses the embedding model (BGE-base-en), the windowing strategy (500-char overlapping windows), and the input cap (200K chars) with truncation behavior and a flag. It also clarifies that output includes character offsets and similarity scores, which is valuable for verification.

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?

A single, dense paragraph that front-loads the purpose and then details usage and technical constraints. Every sentence contributes distinct information, and no filler is present.

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

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

With no output schema, the description compensates by explaining return values (passages, offsets, similarity scores), truncation handling, and the pairing with ask_pipeworx_grounded. The tool is complex, but the description leaves no critical gaps.

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

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

The schema already provides 100% coverage with examples in query, so the baseline is 3. The description adds context by characterizing text as 'already pulled' and noting output includes offsets and scores, which helps the agent understand parameter roles. However, much of this is redundant with the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' using a specific verb and resource scope. It clearly distinguishes from siblings by emphasizing that the search operates on text already obtained, not on external sources. The examples (SEC 10-K, article) further clarify the intended input.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also names a complementary tool, ask_pipeworx_grounded, and describes the intended workflow, giving the agent clear decision criteria.

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 meaningful behavioral context beyond annotations, such as auth requirements, return value, feed pull mechanism, and SMS constraints. However, it omits webhook as a delivery channel (present in the schema) and does not clarify idempotency behavior despite the idempotentHint annotation, leaving gaps in how the tool behaves in edge cases.

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

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

The description is dense but well-structured, with clear sections for types and delivery channels. It packs meaningful examples and constraints (phone verification, 10/day cap) into a compact format without empty sentences, though the omission of webhook keeps it from being fully comprehensive.

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 core use case, return value, and delivery basics, but it fails to list two of the five supported types (patent_grant, clinical_trial) and omits the webhook delivery option that appears in the schema. Given the tool has no output schema and nested parameters, these gaps are significant for an agent selecting the correct usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches several type parameters with concrete examples (e.g., sec_8k items:['5.02'] meaning officer change, polymarket_edge topic:'fed') and adds delivery details, providing value beyond the schema. However, it does not mention patent_grant or clinical_trial types offered in the schema, slightly reducing completeness.

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 with a specific verb ('Create') and resource ('subscription') in the context of proactive monitoring of live-data event streams. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and it mentions the return of a subscription id, making the primary function unambiguous.

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

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

The description provides important usage context, including the requirement for a Pipeworx OAuth account and the always-on feed as a pull-based alternative via recent_alerts, implying when to use this tool for proactive alerts. However, it does not explicitly contrast with other monitoring tools like polymarket_edge_tracker or explain when to choose one delivery channel over another.

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

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

The description discloses that results are category-bucketed example questions each with the exact tool + argument shape, drawn from the live catalog. It also explains the effect of passing topic (focus) versus no arguments (full spread). Annotations already cover read-only/idempotent hints, and the description adds output structure and catalog dependency without contradicting.

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

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

The description is well-structured, starting with example queries, then purpose, output details, and usage guidance. Every sentence contributes actionable information and there is minimal redundancy, making it appropriately sized for an onboarding tool.

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

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

Even without an output schema, the description explains what is returned (category-bucketed examples with tool+argument shape), how to use it (with or without topic), and when to use it (FIRST, learning meta-tools). Annotations cover safety, so the description is complete for its context.

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

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

The schema fully describes the optional topic parameter with values and omit behavior (100% coverage). The description reiterates this with examples but adds no substantial new parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shape, and positions it as the onboarding entry point. It distinguishes from siblings by saying 'Use this FIRST' and mentions learning to call meta-tools like ask_pipeworx, entity_profile, providing a specific verb+resource with 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?

The description lists trigger phrases ('what can I ask Pipeworx?', 'what is Pipeworx good for?', 'give me ideas') and explicitly says to use it FIRST when you don't know capabilities, or to learn to call meta-tools. This gives clear when-to-use context and differentiates from alternatives like ask_pipeworx.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement, deactivation vs. deletion, and the connection to recent_alerts. This reveals side effects and access constraints that annotations alone (readOnlyHint=false, destructiveHint=false) 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?

Two sentences, front-loaded with the primary action, followed by essential behavioral details. Every sentence earns its place with zero waste.

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

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

For a simple single-parameter operation with no output schema, the description is complete. It covers the mutation's effect (deactivation), constraints (ownership), and downstream data availability, making it self-sufficient.

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

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

Schema coverage is 100% for the single parameter id, and the schema already describes it as the uuid from subscribe. The description doesn't add new parameter semantics but doesn't need to; 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 action ('Cancel a subscription by id') with a specific verb and resource. It also distinguishes from sibling tools like subscribe and list_subscriptions by noting the deactivation behavior and ownership enforcement.

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

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

The description provides clear context for when to use the tool (canceling a subscription) and notes the ownership constraint and that historical data remains accessible. It doesn't explicitly name alternative tools or when not to use it, but the context is sufficient.

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

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

Beyond the read-only, open-world, and idempotent annotations, the description discloses the two-path routing (SEC EDGAR/XBRL vs. grounded pipeline), the verdict set, and critical semantics for could_not_verify vs. unsupported, explicitly warning that could_not_verify is not evidence. This provides substantial behavioral context beyond what annotations convey.

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

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

The description is efficiently organized: trigger phrases and purpose upfront, then routing, return values, and caller warnings in separate paragraphs. Every sentence contributes essential information without fluff, making it concise for the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return values (verdict, actual value, citation, reasoning), explains the special verdicts could_not_verify and unsupported, and describes the two processing paths. This gives an agent enough information to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, with both claim and tolerance_pct fully described in the schema, including tolerance_pct's default and override behavior. The main description adds routing context but does not materially enhance parameter-specific meaning beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description opens with concrete trigger phrases and explicitly states 'natural-language claim verification against authoritative sources.' It distinguishes two processing paths (company-financial vs. other factual claims) and lists the verdict types, making the tool's scope unmistakable. This clearly separates it from sibling research or analysis 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and adds that it replaces 4–6 sequential calls, giving a clear preference rationale. However, it does not explicitly name alternate tools or provide when-not-to-use conditions, so it falls short of a full 5.

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