Business Feeds

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's added value is the cost implication ('you pay Anthropic directly') and default model selection, plus the explicit per-model return shape. This goes beyond the structured annotations without contradicting them.

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 tightly-packed sentences: core action, model/cost caveat, and return format + use cases. Front-loaded with the most important information and zero 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?

Despite lacking an output schema, the description names the exact per-model fields (score, confidence, signals, raw_response) and combined view, plus practical use cases and cost behavior. Together with full schema coverage and read-only annotations, this is 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?

With 100% schema coverage, the baseline is 3; the description adds meaningful context by naming the default model (Workers AI Llama-3.3-70b) and explicitly linking _apiKey to cost and the 'anthropic' models option. This gives the agent a better mental model of how the parameters interact.

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

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

The description opens with a specific verb-resource pairing: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research, and the inclusion of return format and use cases leaves no 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 clear usage context via 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains the model/cost tradeoffs (default free Workers AI vs. BYO-key Anthropic). It does not explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it for visibility checks.

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 readOnlyHint, openWorldHint, and idempotentHint already in annotations, the description adds useful behavior: the tool fills arguments, routes across 5,710 tools, and returns structured answers with stable pipeworx:// citation URIs. It also signals that web search can be bypassed. There is no contradiction with the annotations, so the safety profile is consistent.

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

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

The description is front-loaded with the most important routing cue ('PREFER OVER WEB SEARCH') and uses lists and examples to communicate breadth. It is longer than necessary, but each clause adds either scope, trigger conditions, or expected output, so the length is justified. The structure is readable and scannable.

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 a high-complexity router with no output schema, yet the description covers what it accepts (natural-language questions), when to use it, what it does internally, and what the answer looks like (structured with pipeworx:// citations). The only notable gap is not contrasting with ask_pipeworx_grounded/beta or deep_research, but an agent can still invoke this tool correctly from the description.

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

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

The input schema already documents all six parameters at 100% coverage, including the primary question string and five aliases. The description does not add new parameter-level details beyond the natural-language usage context, so the baseline of 3 is appropriate; it does not need to compensate for schema gaps because there are none.

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 — routing a natural-language question to the right one of 5,710 source tools and returning a structured, cited answer — rather than merely restating the tool name. It also distinguishes the tool from plain web search. However, it does not explain how this differs from sibling tools like ask_pipeworx_grounded or ask_pipeworx_beta, 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 opens with an explicit preference rule ('PREFER OVER WEB SEARCH'), gives concrete trigger phrases ('what is', 'look up', 'get the latest'), and supplies six examples of appropriate questions. It also says to start here for most questions, which is actionable routing guidance. It lacks an explicit when-not-to-use or a named sibling alternative such as deep_research for multi-part questions.

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/destructive-safe, and the description adds genuinely new behavioral context beyond them: the current test state ('No candidate is active right now'), the comparison workflow against the stable router, and the reassurance that it is a complete functioning router rather than a stub ('Falls back to nothing — this IS a full working router, just the experimental edge').

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

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

Four dense sentences, each earning its place: identity, current state, usage instruction, and fallback behavior. The most decision-relevant fact (beta status) is front-loaded. Slightly long for a simple tool, but the beta-caveat context justifies the length.

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

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

The description covers identity, argument parity, response-shape parity, live candidate state, usage intent, and fallback behavior — enough for an agent to call it correctly. With the schema at 100% coverage, nothing critical is missing; only an explicit example or a comparison against ask_pipeworx_grounded would push this higher.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters and the baseline is 3. The description adds only 'same arguments' as a pointer to ask_pipeworx rather than per-parameter detail, which is acceptable but not additive beyond the schema.

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

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

The description names a specific resource and purpose: 'Beta version of ask_pipeworx: identical universal router (same 5,710 tools, same arguments, same response shape)'. It clearly differentiates from the stable ask_pipeworx sibling by explaining it carries 'candidate routing improvements', so an agent can distinguish it without opening schemas.

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

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

The description gives an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also clarifies scope via 'Falls back to nothing — this IS a full working router', which prevents under-use. It doesn't explicitly state when NOT to use it versus ask_pipeworx_grounded, but the selection context is clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description builds on this with a full behavioral contract: grounded extraction, the exact success shape, and an explicit refusal path enumerating all five refusal reasons. It also discloses the added LLM-call cost, a trait no annotation captures.

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

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

Five sentences, each load-bearing: purpose, routing behavior, return/refusal contract, usage guidance, and cost trade-off. It is dense and slightly hard to scan because sentences 2 and 3 are long, but there is zero 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?

With no output schema, the description correctly carries the full return contract including the refusal variants — essential for a high-complexity tool that routes across 5,710 tools. Slightly short of a 5 because it never illustrates a concrete call or expected response and leaves the internal routing behavior opaque.

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 visible schema entries are self-sufficient ('Your question in natural language. Accepts query, q, prompt, text, input as aliases.'). The description adds no parameter-level details of its own, so the baseline of 3 applies; no compensation is needed.

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?

Opens with a specific verb+mode+resource: 'Hallucination-resistant answer mode for high-stakes reads.' The clause 'Same routing as ask_pipeworx ... then EXTRACTS the answer using ONLY what the tool result contains' differentiates it from the sibling ask_pipeworx, so an agent can distinguish them without opening schemas.

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

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

Explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on ... and the agent must not invent facts' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). Explicit when-not-to-use with named alternative: 'prefer ask_pipeworx for casual lookups,' including the cost basis for that choice.

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

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

Annotations already convey read-only/open-world/idempotent behavior, but the description adds extensive context: resolver contract with market_match_confidence/score/alternatives, low-confidence short-circuiting, closed-market handling, wide-spread illiquidity warnings, parent_event extraction, news fallback behavior, and resolution-rule risk (including flat-50¢ void settlements). It also details blocking routes and suppressed fields, going far beyond the safety profile implied by 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, using clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loading the core purpose. Most sentences add operational value, though some redundancy exists (e.g., repeated explanation of blocking routes for closed markets) that could be trimmed for conciseness.

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

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

With no output schema, the description carries full responsibility for explaining return values and edge cases. It thoroughly documents response shapes (result.market, result.analysis, result.evidence), status codes (low_confidence_match, market_closed_or_inactive), the resolver contract (match confidence, score, alternatives), parent_event extractor, news fallback fields, and cancellation-rule risk. It covers both normal and failure modes, making it operationally complete for an agent.

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

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

Schema description coverage is 100%, so all parameters (market, depth, include_raw) are already fully documented with descriptions and defaults. The tool description reinforces the market parameter's accepted formats and mentions depth-related fan-out, but it does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Research a Polymarket bet'), the resource (a specific market), and the mechanism ('pulling the relevant Pipeworx data... in one call'). It distinguishes this tool from siblings like polymarket_edges by focusing on a single bet and providing category-specific data packs, with concrete input examples (slug, URL, question text).

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

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

Explicit when-to-use guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples. However, it does not explicitly name alternative tools or state when not to use it (e.g., for multi-market scanning), 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?

Annotations already declare this as read-only and idempotent, but the description adds substantial behavioral context: off-calendar fiscal years are handled correctly, results are sorted by primary metric, and output includes paired data plus citation URIs. This goes beyond the safe-profile hints and gives valuable operational detail.

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 delivers value: examples, preference rule, data sources, sorting, and output format. It is front-loaded with the core capability and avoids filler or repetition. The length is justified by the breadth of behavior it must convey.

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

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

For a tool with no output schema, the description covers the essential context: what it does, when to use it, what data it retrieves per type, how results are sorted, and what the response includes (paired data + citation URIs). It leaves little to guess about the tool's operation and output.

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

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

Schema coverage is 100% with clear param descriptions, but the tool description adds even more: examples of valid values (['AAPL','MSFT'], ['ozempic','mounjaro']), what each type pulls, and constraints like max 5 min 2. This significantly enhances the bare schema and directly guides usage.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, and lists concrete user query examples. It distinguishes itself from siblings like entity_profile or resolve_entity by emphasizing parallel comparison vs. sequential lookups, and names specific data sources (SEC EDGAR, FAERS).

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', establishing a strong usage directive. It also differentiates behavior by type ('company' vs 'drug') and notes it replaces 8–15 sequential lookups, giving clear when-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?

Annotations already declare read-only, idempotent behavior, and the description adds important non-obvious traits: results come only from structured sources, gaps are explicit and never invented, standard/thorough depths add a gap-recovery hop, and findings carry citation metadata. This goes well beyond what annotations alone 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 well-structured: account gate and sibling alternative come first, then mechanism, best-use case, depth behavior, and return fields. A few repetitions, such as the 1494 sources and 'not open-web' wording, cost some efficiency, but the complexity of the tool justifies most of the length.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does: findings packet, gaps, citation_uri, metadata, and multi-hop behavior are all covered. It also addresses authentication requirements and provides a clear alternative tool, 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?

Schema coverage is 100%, so the baseline is 3, but the description adds extra meaning beyond the schema: which depth requires the paid tier, how the multi-hop gap-recovery works, and that the question can be broad or multi-part. This enrichment supports correct parameter choice.

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

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

The description states a specific verb and resource: grounded multi-source research over Pipeworx's structured data sources, with explicit mechanics like decomposing into facets and routing in parallel. It also explicitly says this is NOT open-web search, which distinguishes it from general search tools and siblings.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and 'For a single lookup use ask_pipeworx instead.' It also names ask_pipeworx as the alternative for not-signed-in users, making the routing decision clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond this: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states 'no second schema lookup needed.' This tells the agent what to expect from the response and saves an extra call. 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?

Description is four sentences, each earning its place: purpose, usage, return behavior, and ordering cue. The domain list is long but informative. No redundant phrases or irrelevant details. Properly front-loaded with the core verb.

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 discovery tool with rich annotations and full schema, the description is complete enough. It explains what the tool returns (top-N tools with schemas and examples), which is the main missing piece without an output schema. It does not cover error handling or pagination, but those are not critical here. The overall context is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (query, aliases, limit) in detail. The description adds minimal extra meaning beyond mentioning 'top-N' which maps to the limit parameter. This aligns with 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?

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and enumerates many domains (SEC filings, FDA drugs, etc.), which distinguishes it from siblings like deep_research or validate_claim. The action 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?

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' The phrase 'not just one answer' implies a when-not, but no specific alternative tool is named. This is strong, though not perfectly explicit about 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?

Despite strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral detail: USPTO API sunset soft-fail, GDELT→GNews fallback, data source fan-out, and URL formats. This goes well beyond the annotations, enriching the agent's understanding of what happens when invoked.

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

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

The description is somewhat long but front-loaded with trigger phrases and a clear purpose statement. Each sentence conveys unique info (return fields, limits, fallbacks, prerequisites), so the length is justified for a complex tool. Minor redundancy in the example list prevents a 5.

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

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

With no output schema, the description enumerates all key return components (cik, recent_filings with URIs, fundamentals fields, patents, news, LEI). It also notes limitations and data source nuances. Small gaps like exact counts for news/patents keep it from a 5, but it's largely complete for the agent to set expectations.

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

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

Schema coverage is 100% with good descriptions, and the description adds further value by giving concrete examples (ticker 'AAPL', zero-padded CIK '0000320193'), reinforcing the 'names not supported' constraint, and linking to resolve_entity. This exceeds the baseline for full 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 uses a clear verb phrase ('full cross-source profile') and lists specific return fields, distinguishing it from siblings like resolve_entity and compare_entities. It also includes trigger examples that make the tool's function immediately identifiable.

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 prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to (names not supported, use resolve_entity first). This provides clear alternatives and contextual triggers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway.' This explains network resilience behavior and normalization, which are not inferable from annotations. It stops short of describing return structure or error handling, but given annotation coverage, this is sufficient.

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

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

The description is two sentences: the first states purpose and scope, the second adds usage guidance and a resilience behavior. Every word earns its place, with no filler or repetition of schema/annotation content. The front-loaded verb 'Fetch' immediately signals the tool's action.

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

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

For a tool with only three parameters (all documented) and strong annotations, the description provides sufficient context: what it fetches, how it handles network failures, and a recommended workflow. It does not mention the return format, but there is no output schema, and the behavior of 'normalize' hints at content processing. The only notable gap is not addressing the sibling read_feed, which might be a natural alternative for already-listed feeds, but the guidance to use list_feeds first partially mitigates this.

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

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

Schema coverage is 100%: all three parameters (url, limit, query) have descriptions in the schema. The description itself adds no parameter-specific information beyond the schema; it only mentions normalization and proxy fallback, which are tool-level behaviors. Therefore, the baseline of 3 is appropriate; the description does not need to compensate for schema gaps.

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

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

The description opens with a clear verb-object pair: 'Fetch and normalize any RSS / Atom / RDF feed by URL.' It immediately conveys the tool's scope (any feed format) and its core action (fetching and normalizing). The phrase 'any RSS / Atom / RDF feed' distinguishes it from sibling tools like list_feeds, which is explicitly referenced, and read_feed, which likely has a narrower 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?

The description provides a concrete workflow hint: 'Use list_feeds first for curated sources.' This tells the agent when to call list_feeds before fetch_feed, implying that fetch_feed is for arbitrary or unsourced URLs. However, it does not explicitly mention when to prefer read_feed or other alternatives, and the exclusion is implicit rather than stated as a hard rule.

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

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

Annotations already convey destructive and idempotent hints. The description adds that the deletion targets a 'previously stored memory' and is useful for clearing sensitive data, which provides useful context about the operation's effect without contradicting 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 two sentences, front-loaded with the core action, and every sentence contributes either the operation, usage context, or related-tool guidance. 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 simple single-parameter delete tool with strong annotations (destructive, idempotent), the description plus schema fully cover the tool's purpose, usage, and behavioral context. No output schema is necessary for such an operation.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete.' The description adds minimal semantic value beyond the schema, only reiterating that deletion is by key. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember and recall, which store and retrieve memories respectively.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the complementary tools (remember and recall) to provide context on the workflow.

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 and idempotentHint=true, and the description goes further by detailing the process (fetches the page, extracts content, emits markdown) and output format. This adds behavioral context without contradicting annotations, though rate limits or failure modes are not mentioned.

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 uses four sentences to convey the primary action, process, output format, and use cases. It is front-loaded with the key purpose, every sentence provides value, and there is no unnecessary verbosity.

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

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

With no output schema, the description explicitly states the return value is a single text blob ready to drop at site-root/llms.txt. It also covers the workflow and use cases, making it fully complete for a simple two-parameter tool.

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

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

Schema description coverage is 100% for both parameters (url and max_links), each with clear descriptions. The tool description itself adds no additional parameter-level detail, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL, with specific process details (fetches, extracts title/description/key links, emits standard markdown). It distinguishes itself from sibling tools by focusing on producing the llms.txt format, despite potential overlap in competitor auditing.

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-case scenarios ('getting a client's site indexed by AI, drafting for own project, auditing how an AI crawler would see a competitor'), which imply when to use it. However, it does not explicitly mention alternatives or when-not-to-use, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying the return fields, the curated nature of feeds, and the intended workflow of passing ids to read_feed. It doesn't mention pagination or rate limits, but it's not a gap given the simple read-only nature.

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 extremely concise—two sentences—with the core purpose front-loaded. The second sentence efficiently covers optional filters and the next-step pointer to read_feed. Every word earns its place, with no redundancy or fluff.

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

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

For a simple list tool with rich annotations and no output schema, the description is complete: it states the resource (curated feeds), the returned fields, the two filters, and what to do with results. It lacks pagination or ordering details, but those are not essential for a basic list operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates the category values and keyword filter, adding no new parameter-level meaning beyond what the schema already provides. It does mention returned fields, but that's not parameter semantics.

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

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

The description clearly states the tool lists curated business/industry feeds and specifies the returned fields (id, title, category, source), making its purpose unambiguous. It also distinguishes from siblings by explicitly pointing to read_feed for a single feed.

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

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

The description gives direct usage guidance: optionally filter by category or keyword, and then pass an id to read_feed for full content. It doesn't explicitly contrast with sibling tools like list_subscriptions or fetch_feed, but the read_feed pointer provides a clear next step and a basis for choosing this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the return field names (id, type, params, created_at, last_fired_at, fire_count) and clarifies the scope to the caller's subscriptions, providing 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?

Two sentences, front-loaded with the verb and resource, followed by return fields and usage guidance. No redundant information.

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

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

Given a simple read-only list tool with no output schema, the description covers the return format and typical use cases, and the annotations cover safety. This is sufficient for agent selection and invocation.

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

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

The schema describes the single parameter include_inactive with 100% coverage, so the description need not elaborate. The description's mention of 'active subscriptions' indirectly relates to the parameter, but the schema fully carries the semantic weight.

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 the specific verb 'List' with a clearly defined resource ('the caller's active subscriptions') and explicitly states the returned fields, distinguishing it from sibling tools like subscribe/unsubscribe and list_feeds.

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

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

It provides explicit use cases: 'before adding more' subscriptions and 'to find an id to cancel', telling the agent when to invoke it. However, it doesn't name alternative tools directly, so it's slightly less explicit than ideal.

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 hint of safety (all false), but the description enriches behavior: it mentions sending data to the team, returning a `claim_token` for anonymous use, the ability to check status later, daily rate limits ('Rate-limited to 5 per identifier per day'), and that it is free and doesn't count against tool-call quota. This goes well beyond what annotations disclose and fully describes the side effects of invocation.

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

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

The description is long but every sentence carries unique information: purpose, when to use, exclusion, claim_token mechanics, team behavior, rate limit, and cost. It is front-loaded with the core purpose, then flows logically into usage and behavioral details. There is no fluff or repetition that inflates length without value.

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

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

Given the tool's moderate complexity (feedback routing, token-based lookups, rate limiting, and scoping to Pipeworx tools), the description addresses all essential aspects. It covers required input style, the claim_token return and later usage, the exclusion of other MCP servers, and operational limits. No output schema exists, but the description adequately describes what the tool returns without needing to detail a return structure.

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

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

Schema coverage is 100% with each parameter having its own description, so baseline is 3. The description adds value by explaining the `claim_token` flow (pass it back to read resolution) and by constraining message content ('don't paste the end-user's prompt'). Thus it exceeds the baseline but doesn't radically transform parameter understanding, hence a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly scopes the tool to feedback about Pipeworx itself, distinguishing it from all sibling tools (e.g., research or data-fetching tools) by stating it is for reporting bugs, feature gaps, and praise. This is far beyond a vague purpose statement and helps an agent select it correctly.

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

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

The description explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: if the tool came from a different MCP server, file with that server instead. This is textbook guidance with both positive use cases and negative exclusions.

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

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

Annotations already declare the tool read-only, open-world, and idempotent. The description adds valuable behavioral context beyond these: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data origin, privacy guarantees, and caching behavior, which are important for an agent to understand the freshness and trustworthiness of the data. 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 three sentences long, front-loaded with the core purpose. The second sentence presents clear, bullet-like use cases. The final sentence provides technical caveats (data source, PII, caching) without fluff. Every sentence contributes meaning and there is no redundant information.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains what is returned, the time windows, additional use cases, data provenance, and caching behavior. An agent can confidently decide when to invoke this tool and what to expect from the results.

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

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

The input schema already covers the 'window' parameter with an enum and a description (100% coverage). The description adds meaningful interpretation: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's literal enum values and helps the agent choose the right window for its context. Since schema coverage is high, this extra semantics elevates the score above the baseline 3.

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

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

The description opens with a specific, informative statement about what the tool does: 'What other AI agents are calling on Pipeworx right now.' It clearly states the outputs ('top tools, top packs, and total call volume') and the timeframe ('24h, 7d, or 30d'). This clearly distinguishes it from sibling tools like discover_tools, which likely focuses on listing available tools rather than aggregated 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 explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice before asking your own question,' and 'seeing whether your use case aligns with what most agents need.' While it doesn't name alternative tools for when not to use it, the use cases give clear situational guidance. Lacks explicit exclusionary guidance, thus not a 5.

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

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

Annotations only indicate read-only, open-world, idempotent, non-destructive. The description goes far beyond: it explains the default top-200 market scan, the Jaccard similarity threshold (0.30), placeholder slug filtering behavior, and the fill-check mechanism against live CLOB depth. It also discloses edge cases like thin_legs and when a signal is not tradeable.

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

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

The description is long but extremely well-structured: purpose and mode guidance upfront, then labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes technical or behavioral value, but the density and length make it slightly less concise than a minimal description would be.

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

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

There is no output schema, yet the description fully explains the response shape (`opportunities[]` with fields, `partition_check` in event mode) and the fill-check result fields. It also covers semantic filtering, placeholder edge cases, and actionable guidance on when not to trade, making it completely self-contained.

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 `event` and `topic` with clear descriptions (100% coverage), so the baseline is 3. The description adds the crucial no-args default and elaborates on the operational behavior of each mode (walks child markets, computes partition_check, etc.), which justifies a score above baseline but not 5 since the schema does a lot of the work.

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 states the exact purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb, resource, and method, and distinguishes three modes (trending_scan, event, topic), clearly separating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives explicit when-to-use instructions: call with NO args for trending_scan, pass `event` for a specific market, or `topic` for cross-event scanning. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and warns against trading when realizable_edge_pp ≤ 0.

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, establishing safety. The description adds substantial behavioral context: output structure (by_segment, diagnostics), edge calculations (net of slippage, Kelly caps), caching (1h KV keyed on knobs), and caveats (e.g., Fed signal unreliability, rare-by-design concentrated longshots). This goes well beyond the annotations.

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

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

The description is long but information-dense, with clear section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds value and avoids fluff. It could be more scannable with bullet points, but the structure is effective for the tool's complexity.

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

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

With no output schema, the description thoroughly specifies return format: by_segment segments, fed_candidates/fed_note, _diagnostics with funnel counters and filter_skips. It also covers empty-segment explanations, edge cases (placeholder-slug filters, partitions with >20% placeholder), and the 24h-move warning. Complete for a complex tool with 9 params.

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 semantic value by grouping parameters (TRADEABLE-EDGE KNOBS) and explaining subtle behavior: e.g., min_partition_leg_kelly applies to per-leg Kelly not parent, and partition arbs always return kelly_fraction_half=0, so min_kelly doesn't filter them. This enriches understanding beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes it from siblings by focusing on current opportunities and Pipeworx disagreement, not generic market data or arbitrage.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on knobs (e.g., min_liquidity, max_spread_pp) to filter tradable edges. However, it does not explicitly mention alternative tools or when not to use it, though the context of siblings is clear.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses significant behavioral details: the 60-day snapshot TTL, that snapshots are written on cache-miss and gaps mean no scan, that decay is based on daily closes rather than intraday, and that edge_pp_net is signed (negative = SELL YES). This is exactly the kind of 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 description is long but well-structured with clear sections (purpose, args, response, limits). Every sentence carries operational value, but it could be tightened slightly without losing information. Still, the structure compensates for length.

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

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

With no output schema, the description fully documents the response object: tracked[] with time-series and trend/decay fields, expired[] with lifespan_days, and snapshot_dates[] with gap semantics. It also covers data limitations and the meaning of derived metrics, making it highly complete for a tool of this complexity.

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

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

Both parameters are already fully described in the input schema (days lookback with clamp 2-30, window family enumeration). The description's Args section simply repeats these defaults and meanings, adding no new semantic value. Since schema coverage is 100%, 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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?', clearly distinguishing it from the sibling polymarket_edges tool. It names the specific resource (snapshot history) and the analytical operation (tracking edge persistence/decay).

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

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

The description provides a clear use case: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)' and explains that it reads historical snapshots. However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral context beyond annotations: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), identifies forced_directional_risk, and explains that basket fills can strand the user unhedged. This is rich, non-obvious behavior that is essential for safe invocation.

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 modes (SINGLE-MARKET, BASKET), a clear first-sentence purpose, and a final usage warning. Every section adds value, but the length is substantial and could potentially be trimmed by removing some output-field enumeration, especially since no output schema exists to cover it. Still, the structure is excellent 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?

The tool is highly complex (two modes, no output schema, safety-critical usage). The description fully covers return values for both modes, parameter semantics, mode selection prerequisites ('REQUIRES one of market or event'), and risk context. Given the absence of an output schema, the description carries the burden of explaining outputs, and it does so thoroughly. It is complete for an AI agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds significant mode-dependent meaning: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S (shares per leg)' in basket mode. It also explains the default side behavior in basket mode ('auto — sell if partition sum > 1, buy if < 1'). This goes well beyond the schema's generic 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines both single-market and basket modes, and distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as tools that should be preceded by this check.

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

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

Usage is explicitly prescribed: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides a rationale (theoretical overround on thin books is not capturable) and warns about the dominant loss mode (partial fills convert an arb into a directional position), giving clear when and 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?

The description goes far beyond the read-only/idempotent annotations by enumerating compatibility codes, skipped-leg counters, unclassified-leg exclusion rules, temporal alignment, and the caveat that warnings can coexist with returned pairs. This gives an agent accurate expectations about the tool's output and 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 long but well-structured with labeled sections and front-loaded core purpose. Some enumerations could be trimmed, yet each section carries behavioral information that is not available from the schema or annotations.

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 thoroughly: it explains the response shape, the Kalshi − Polymarket sign convention, safety fields, compatibility codes, skipped counters, and the low-confidence inspection path. An agent has enough context to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that topic shortcuts auto-fetch the matching event on each venue and that the explicit parameters enable custom pairings. It also contextualizes the topic values and the behavior of non-empty compatibility fields.

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 computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, and it distinguishes the two operation modes. It stops short of naming sibling tools like polymarket_arbitrage or polymarket_edges, so some cross-tool differentiation is left implicit.

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 lays out when to use each mode: topic shortcuts auto-fetch mapped events, while explicit ticker and slug support custom pairings. It also warns that pre-mapped topics are not necessarily tradeable. It does not give explicit criteria for choosing this tool over sibling Polymarket tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns normalized items (title, link, published, summary) and supports optional keyword filtering, which is useful context. However, it doesn't disclose more nuanced behavior like pagination or error handling, so it matches the baseline for annotation-covered safety.

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

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

The description is two sentences, front-loaded with the main action, and every clause adds value. It states the input requirement, output format, and an optional behavior without any filler.

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

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

For a simple read tool with 3 params and no output schema, the description adequately covers the return format and basic functionality. The limit parameter is detailed in the schema, so the description doesn't need to repeat it. It is nearly complete, though it could mention that the feed id must come from list_feeds (which it does) and perhaps clarify that the tool is safe to call multiple times (but that's in annotations).

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds only marginal meaning by saying 'by its id (from list_feeds)' for the feed parameter, but it doesn't add detail beyond what the schema provides. The schema's description of query ('Keyword filter over item title/summary') is actually more specific than the tool description's 'filter items by keyword', so no extra value.

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

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

The description clearly states the tool's purpose: 'Read a curated business & industry feed by its id'. It uses a specific verb ('Read') and names the resource (feed) and context (curated). However, it does not explicitly differentiate from sibling tools like fetch_feed, so it doesn't fully earn a 5.

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 by referencing list_feeds as the source of the id, which is a prerequisite. It does not explicitly state when to use this tool vs alternatives or provide exclusions. This is implied usage rather than clear guidance, so it falls short of a 4.

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. The description adds valuable behavioral context beyond those: scoping to the user's identifier ('anonymous IP, BYO key hash, or account ID') and the behavior of omitting the key to list all saved keys. 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 three sentences, each earning its place: the first states the core action, the second gives concrete use cases, and the third covers scope and pairing with sibling tools. No wasted words and the main purpose is 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?

This is a simple tool with one optional parameter. The description covers purpose, behavior (list vs retrieve), scope, and sibling relationships. With annotations covering safety, and no output schema needed for such a straightforward lookup, the description is fully adequate.

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

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

The input schema already covers the single 'key' parameter with a description that includes the omit-to-list behavior, giving 100% schema coverage. The description reinforces this with examples and clarifies the parameter's role, but adds no syntax or format details beyond the schema, 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 begins with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools like remember and forget by stating the read/lookup role and even names its counterpart 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 states when to use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references sibling tools ('Pair with remember to save, forget to delete') to guide selection among alternatives, though it does not explicitly state when not to use it.

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

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

The description discloses important behavioral details beyond annotations, such as the mark_read:true side effect (flags events as read) and the feed's persistence. Annotations already cover read-only/idempotence, and the description adds nuance without contradiction.

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

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

The description is concise, front-loaded with the core action, and packs useful detail into just three sentences. It includes return payload info, filtering options, mark_read behavior, and an alternative endpoint, 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 read-oriented tool with complete schema annotations, the description covers purpose, behavior, output fields, filtering, and alternative access. No output schema exists, but the description adequately describes the return content. It is complete.

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

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

Schema coverage is 100%, with all five parameters clearly described. The description mentions filtering by type and since but adds no extra semantic depth beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed' and specifies it returns 'the most recent alerts' with details like source and citation_uri. It distinguishes from siblings by focusing on persistent feed alerts written by the evaluator, not generic feed reads.

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 clear context for when to use this tool ('Polls work fine') and mentions an alternative HTTP endpoint for scripts/dashboards. It doesn't explicitly exclude sibling tools like read_feed, but the usage context is strong enough for an agent to choose appropriately.

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 rich behavioral detail beyond the annotations: fan-out to multiple sources (SEC EDGAR, GDELT/GNews with fallback logic), soft-fail behavior for USPTO due to PatentsView sunset, and parallel execution. It also describes the return structure (changes[] grouped by source, total_changes count, citation URIs).

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

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

The description is dense but well-structured, front-loaded with query examples. Every sentence adds value (sources, fallback, return format, alternative). It is slightly long but appropriate 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?

For a tool with no output schema, the description thoroughly explains return values, source integration, edge cases (rate limiting, soft-fail), and temporal parameter syntax. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context about the 'since' parameter (ISO or relative shorthand) but this largely duplicates the schema's own description. No significant new parameter semantics are introduced.

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 time window, with explicit query examples ("What's new with X", "updates on Acme"). It distinguishes itself from the sibling entity_profile tool by explicitly naming the alternative for static profiles.

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

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

The description provides explicit when-to-use guidance through user-intent examples and states when NOT to use it: 'Use entity_profile instead when you want the static profile...'. This is a clear alternative, fulfilling the usage guidelines criterion.

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 idempotentHint and destructiveHint annotations, the description adds meaningful behavioral context: key-value pairing, scoping by identifier, persistence differences between authenticated and anonymous sessions, and retention window (24h).

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 efficiently pack purpose, usage, storage model, retention, and sibling relationships—no wasted words.

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

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

For a simple write operation, the description is complete: it specifies when to use, how data is stored, how long it persists, and related tools, covering everything an agent needs to invoke it correctly.

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

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

The input schema covers both parameters fully (key, value) with examples. The description doesn't add significantly to parameter semantics, so baseline 3 applies.

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

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

The description opens with a specific action ('Save data the agent will need to reuse later'), clearly defines the resource (data across conversations/sessions), and differentiates from siblings by explicitly referencing recall and forget.

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

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

It explicitly tells when to use ('Use when you discover something worth carrying forward') and names complementary/alternative tools ('Pair with recall to retrieve later, forget to delete').

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, and idempotentHint. The description adds valuable behavioral context: it cascades through multiple internal endpoints, degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), labels identifiers with source, and explicitly states unresolved identifiers. No contradiction with annotations.

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

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

The description is well-structured with front-loaded examples, then purpose, then details. Every sentence adds value, but it is relatively long (~120 words). A slightly tighter edit could achieve a 5, but it remains clear and efficient.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (identifiers, source labels, unresolved list), how it handles errors (graceful degradation), and covers all supported entity types. Given the tool's complexity (multiple identifier sources, two entity types), the description is complete and leaves no major gaps.

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

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

Schema coverage is 100% (both parameters described). The description goes far beyond the schema by providing examples of acceptable inputs (ticker, CIK, ISIN, company name for 'company'; brand or generic name for 'drug'), explaining how ISINs resolve to legal entities, and detailing the enrichment behavior. This adds substantial meaning for the agent.

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 specific example queries ('What's the ticker for…', 'find the CIK for…') and clearly states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes between two supported types (company, drug) and explains what each returns, making it easy to differentiate from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It provides concrete examples of when to invoke the tool (e.g., ticker lookups, CIK lookups, drug RxCUI lookups). However, it does not explicitly state when not to use the tool or mention alternative tools for related tasks, which would strengthen guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds meaningful behavioral detail: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond structured annotations without contradicting them.

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: main action, process detail, and use case. No redundant phrasing. The description is front-loaded with the core purpose.

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

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

With annotations covering safety and schema covering all parameters, the description fills the remaining gap by explaining the output format (ranked list with score, confidence, signal density) and the sub-tool used. This is complete for a read-only comparison tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'your brand + N competitors' which aligns with the entities parameter, and 'per probe' hints at models/_apiKey usage, but it doesn't add significant meaning beyond what the schema already documents. The schema carries the parameter-semantics burden.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling ai_visibility_check by explaining that it probes each entity with that underlying tool and then ranks results. This makes 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 provides a clear use case: competitive AI-marketing audits, with an example query. It implies this is the multi-entity comparison variant of ai_visibility_check, but does not explicitly name alternatives or state when not to use it. Still, the usage context is clear enough.

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

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

Annotations already indicate read-only/idempotent behavior. The description adds substantial context beyond that: it fans out to two external services, may take 5-30s on first bundlephobia measurement, degrades gracefully on partial failures, and lists sources_failed behavior. This is rich behavioral disclosure.

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 longer than average, every segment earns its place: purpose, trigger cases, return fields, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and flows logically, with no fluff or repetition.

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

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

Given the absence of an output schema and the tool's composite nature, the description fully covers inputs, outputs, external dependencies, latency, failure modes, and ecosystem constraints. An agent has enough information to invoke it appropriately and interpret results.

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

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

Schema coverage is 100% for both parameters, and the schema already describes package names, scoped support, and version defaulting. The description does not add meaningful parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and outcome: a composite 'should I add this npm package to my project' check in ONE call. It clearly distinguishes itself from sibling tools by naming its data sources (deps.dev and bundlephobia) and the exact metrics returned.

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

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

It provides explicit trigger phrases ('is X safe / popular / small', 'what does adding lodash cost me') and explicit exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This answers when to use it and when not to.

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

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

Discloses return format (passages with offsets and similarity scores), embedding model (BGE-base-en), chunking (500-char overlapping windows), and the 200K char cap with truncation flagging. All of this exceeds the readOnly/idempotent hints and adds 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?

Three focused sentences, each earning its place. The first sentence captures the core action, the second adds usage context, and the third gives technical details. 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 3 params and no output schema, the description fully covers the return format, edge cases (truncation), and integration with a sibling. The agent can confidently select and invoke the tool without ambiguity.

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 beyond the schema by explaining the truncation behavior for the text parameter and the nature of the query with practical examples, plus the offset-based verification benefit.

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

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

The description clearly states the tool performs semantic search inside an already-fetched record, distinguishing it from sibling tools like ask_pipeworx_grounded. It gives concrete examples (SEC 10-K, article, tool result) and emphasizes 'INSIDE' to signal scope.

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

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

Explicitly says to use when the record is too big to cram into the prompt, and pairs with ask_pipeworx_grounded for a fetch-then-ground workflow. This provides clear when-to-use and alternative guidance.

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

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

The description adds extensive behavioral detail beyond the annotations: requires a Pipeworx OAuth account (anonymous cannot persist), returns subscription id, delivery channels with phone verification and daily cap, webhook auto-disable after 10 failures, and one-time signing secret. This exceeds the baseline provided by readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and contradicts none.

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

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

The description is front-loaded with the core purpose and then details types and delivery. It is dense but each sentence provides necessary operational detail. However, it is a bit long and could benefit from bullet points, but it does not waste words. The omission of two supported types (patent_grant, clinical_trial) from the list is a minor structural issue.

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

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

For a complex tool with nested objects and multiple types, the description covers most aspects: authentication, return value, delivery options, and specific examples. However, it claims 'Supported types' but lists only three of the five enumerated in the schema, omitting patent_grant and clinical_trial. This is a completeness gap, though the schema fills it. Overall, the description is rich but not fully exhaustive.

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 goes far beyond by providing concrete examples for each subscription type (e.g., items:["5.02"] = officer change for sec_8k), delivery channel requirements (phone must be verified, webhook restrictions, signing secret), and constraints. This adds significant meaning beyond the schema.

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

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

The description clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe, and provides a specific resource (live-data event stream subscription).

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 context for when to use the tool: proactive monitoring with specific subscription types. It also includes prerequisites (OAuth account, phone verification for SMS) and delivery channels. However, it does not explicitly compare to alternatives like recent_alerts or fetch_feed, so it lacks an explicit 'when vs. not' statement, but the context is strong.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds that the suggestions are drawn from a live catalog and include tool+argument shapes, which explains why the output can change. 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 a bit long but every clause adds useful information—intuitive user queries, what it returns, usage options, and timing. It is front-loaded with the question patterns and ends with actionable guidance, so the length is justified.

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

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

With only one optional parameter and no output schema, the description adequately explains the return content, the customization via 'topic', and the appropriate time to use the tool. The lack of output schema is mitigated by describing the nature of the results.

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

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

The schema already provides 100% coverage for the 'topic' parameter with full value list. The description adds a few examples and clarifies that omitting the parameter gives a cross-category spread, but this is marginal beyond what the schema offers.

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

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

The description clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It also distinguishes itself from siblings like discover_tools by focusing on 'what to ask' rather than just discovering 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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call meta-tools, giving direct when-to-use instructions. It also differentiates between no-argument and topic-filtered 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?

The description reveals important behavioral details beyond the annotations: ownership enforcement, soft-delete behavior (deactivation vs deletion), and that historical events remain accessible. The annotations already indicate idempotency and non-destructiveness, and the description adds complementary context without contradiction.

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

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

Two concise, front-loaded sentences. The first sentence states the core action, and the second explains the key behavioral nuance (deactivation and historical availability). Every word adds value; 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 simple single-parameter mutation tool with strong annotations, the description is quite complete. It addresses ownership, the soft-delete behavior, and the impact on historical data. It does not mention return values or error cases, but these are not essential given the tool's simplicity.

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

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

The input schema fully documents the single parameter 'id' with its type and source ('Subscription id (uuid) returned by subscribe'). The description adds minimal new information ('by id'), but since schema coverage is 100%, 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 clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, and explicitly distinguishes this from deletion by noting the row is deactivated. This also sets it apart from sibling tools like subscribe and list_subscriptions.

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 useful context about ownership ('you can only cancel your own subscriptions') and hints at an alternative path for historical events via recent_alerts. While it doesn't explicitly list when-not-to-use scenarios, the ownership constraint and reference to recent_alerts give clear usage direction.

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

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

Annotations already indicate readOnly/openWorld/idempotent, but the description adds meaningful behavioral detail: the verdict taxonomy, the distinction between could_not_verify (failure) and unsupported (no source coverage), the verification_error{stage,detail} payload, and the explicit warning not to treat could_not_verify as evidence. This goes well beyond structured fields.

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

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

The description is long but densely packed with essential trigger phrases, routing logic, verdict definitions, and error semantics. Every sentence contributes—no filler or redundancy—and the most important usage guidance is 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 tool with no output schema, the description fully defines the return value (verdicts, actual value with pipeworx:// citation, reasoning) and the failure mode (verification_error with stage and detail). It also explains how it replaces multiple sequential calls, giving a complete operational picture.

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

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

Schema has 100% coverage, but the description enhances both parameters: it gives concrete examples for 'claim' and explains tolerance_pct semantics, default behavior (implied by wording, capped at 5), and a use case (1–2 for hallucination detection). This adds value beyond the schema.

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

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

The description clearly identifies a specific verb+resource: natural-language claim verification against authoritative sources. It includes explicit trigger phrases ('fact check', 'verify the claim that…') and distinguishes this tool from sibling tools by its verification focus and dual pipeline for company-financial vs. other claims.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional routing guidance (SEC EDGAR fast path for company-financial claims, grounded pipeline otherwise) and clarifies the meaning of could_not_verify/unsupported so callers don't misuse results.

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