Space Feeds

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the default model is free, Anthropic calls require a user-provided key and direct payment, and it returns a structured per-model payload plus a combined view. This goes beyond the annotations, though it does not cover failure modes or rate limits.

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 entire description is three sentences, packed with essential information: purpose, model options, cost note, output shape, and use cases. Every sentence earns its place with no redundancy, and the main verb appears immediately.

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

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

Given there is no output schema, the description compensates by specifying the per-model return fields ({score, confidence, signals, raw_response}) and a combined view. It also covers model selection and cost. It falls slightly short of a 5 because 'signals' and 'combined view' are vague, but the tool's essentials are well-covered.

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

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

Schema coverage is 100%, so each parameter is already described. The description enriches these semantics by explaining the free default for 'models', the cost implication for '_apiKey', and the disambiguation benefit of 'context'. This adds meaningful usage nuance beyond the bare schema definitions.

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

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

The description opens with a specific verb+resource: '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 siblings like ask_pipeworx (which likely answers queries) and scan_competitor_ai_presence (which may inspect competitors), by focusing on scoring AI visibility across models.

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 phrase 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' provides clear use cases. It also explains the choice between the free default (Workers AI) and the optional Anthropic model with a BYO key, giving practical guidance. However, it does not explicitly contrast with sibling tools or 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description goes beyond this by revealing internal behavior: it routes to 5,439 tools, fills arguments, returns structured answers with citation URIs, and works on every tier in one fast call. This adds meaningful context about the tool's operation that annotations do not convey, earning a 4 rather than the baseline 3.

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 and well-organized. It front-loads the core directive ('PREFER OVER WEB SEARCH'), then layers domains, examples, and alternatives. Some repetition exists (e.g., 'current or historical data' followed by exhaustive domain list), but every sentence contributes to decision-making. Not a 5 because it could be tightened, but it earns a 4.

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

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

Given the tool's complexity (routing to thousands of tools) and absence of an output schema, the description fully covers what the tool does, what it returns (structured answer with pipeworx:// citation URIs), when to use it, and when to step up to siblings. It also addresses edge cases like breaking news and free-tier limitations, 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. However, the description enriches the 'question' parameter by defining its acceptable scope (SEC filings, FDA data, economic stats, weather, etc.) and providing concrete examples of natural-language queries. This goes beyond the schema's generic 'Your question or request in natural language' and helps the agent formulate appropriate inputs.

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, specific verb ('routes', 'returns') and identifies the resource (5,439 tools across 1,412 verified sources) with an unambiguous scope (factual questions requiring authoritative data). It also explicitly distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, which is exactly what purpose clarity requires.

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

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

Usage guidance is exceptionally explicit: it starts with 'PREFER OVER WEB SEARCH', gives trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), provides concrete examples, and states both when to use alternatives ('Step up only when needed') and when not to (breaking news). It even mentions free-tier availability, leaving no ambiguity about when to select this tool.

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

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

The description discloses the experimental behavior beyond annotations: candidates may be enabled live under test, currently no candidate is active (last retired 2026-07-26), and it matches ask_pipeworx exactly at the moment. It also notes that it's a full working router, not a stub. These traits add valuable context beyond the read-only/idempotent hints.

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

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

The description is four sentences and front-loaded with the core purpose, followed by current state, usage, and a clarifying note. It's slightly redundant (mentions 'identical' and 'matches exactly' multiple times) but every sentence provides essential context. Could be tightened without losing value.

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

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

The description covers purpose, current behavior, usage, and the fact that it's a full router. It references 'same response shape' as ask_pipeworx rather than detailing return values, but given the lack of an output schema and the tool's role as a variant, this is acceptable. The 5,439-tool count and comparison workflow add useful context.

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

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

Schema coverage is 100% with all six parameters (aliases for 'question') documented, so the description doesn't need to add parameter details. The description only refers to 'same arguments' as ask_pipeworx, which adds no 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 states this is the beta version of ask_pipeworx, an identical universal router with the same 5,439 tools and response shape, but with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by explicitly noting its beta/experimental nature and that it currently matches ask_pipeworx exactly.

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

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

The description explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. It also clarifies that it is a full working router with no fallback, preventing misuse.

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 annotations by detailing the refusal mechanism (exact refusal_reason enumerations), the evidence verbatim quote, and the one extra LLM call cost. Annotations (readOnlyHint, idempotentHint, etc.) already cover safety, so this extra context is additive. No contradictions.

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

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

The description is information-dense and well-structured: purpose, mechanism, output/refusal format, and usage tradeoff are each addressed in distinct, essential sentences. No unnecessary fluff; every sentence earns its place.

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

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

Though no output schema exists, the description explicitly defines the success return shape and all refusal_reason enum values. It also explains the tradeoff vs ask_pipeworx, covering cost, use cases, and behavior comprehensively for the tool's complexity.

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

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

Schema description coverage is 100%: the 'question' parameter and its aliases are fully documented in the schema. The description does not add parameter-level detail beyond what the schema provides, which is the baseline 3 for high coverage.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains its function: it routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. It distinguishes itself from sibling ask_pipeworx by highlighting the grounded extraction and refusal behavior.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also contrasts with ask_pipeworx by noting the extra LLM call and advising 'prefer ask_pipeworx for casual lookups.'

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, so the description doesn't need to repeat safety. It goes far beyond with detailed behavioral contracts: low-confidence short-circuits, blocking behavior, closed-market handling, news fallback with retry_after_sec, wide-spread illiquidity flag, and cancellation-rule parsing. This is exemplary 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?

The description is extremely long but well-structured into sections (RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) and front-loaded with purpose and usage. Every section provides actionable detail for a complex tool. It's not concise, but it's appropriately dense; a few examples could be trimmed but overall each sentence earns its place.

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

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

With no output schema, the description fully specifies response shapes (market, analysis, evidence, parent_event, news fields), status codes, edge cases, and safety mechanisms. It also covers the resolution-rule risk explicitly, which is a non-obvious pure-rules loss scenario. This is a model description for a high-complexity 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%, and the schema already documents market formats, depth, and include_raw semantics. The description adds no new parameter-level information beyond what the schema provides, so a 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 gives a specific verb ('Research a Polymarket bet'), resource (Polymarket market via Pipeworx data), and unique behavior (resolves, classifies, fans out to category-specific data packs). It clearly distinguishes from siblings like polymarket_edges or deep_research by focusing on market-specific evidence retrieval in one call.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') with concrete examples. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool over general research or edge-finding tools.

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

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

The description discloses specific data sources (SEC EDGAR/XBRL, FAERS), handles edge cases (off-calendar fiscal years), and describes result sorting and citation URIs. This goes well beyond the annotations, which only state read-only and idempotent hints, and provides no contradiction.

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

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

The description is dense but each sentence delivers value: trigger phrases, scope, data sources, edge-case handling, and efficiency claim. It is front-loaded with user intents and well-structured, with no 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?

Given the tool's complexity and absence of an output schema, the description fully compensates by specifying return contents (paired data + citation URIs) and sorting behavior. It also covers both entity types and fiscal year nuances, making it comprehensive for an AI 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?

Even though schema coverage is 100%, the description adds meaning by explaining what each type pulls (company financials vs drug trial counts), gives examples for values, and notes max 5 items. This enriches the schema's basic enum and array descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific trigger examples ("Compare X and Y", "which is bigger") and distinguishes from sequential single-pack lookups, making the 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?

Explicit guidance is given: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also specifies the appropriate entity types (company/drug) and response sorting by primary metric, giving the agent clear when-to-use and when-not-to-use context.

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

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

While annotations declare readOnly/openWorld/idempotent, the description adds crucial behavioral context: account requirement and paid tier, the guarantee of never inventing answers (explicit gaps[]), the hop field for multi-step iteration, contradiction detection, semantic excerpting of large records, and expected latency ranges. This goes well beyond what annotations provide.

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

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

The description is long but densely packed with value: account prerequisites, tool boundaries, return format, depth semantics, and latency all appear front-loaded. The structure uses parentheticals and semicolons effectively, though it could be broken into clearer sections. Every sentence contributes, but it is not 'appropriately sized' in the concise sense.

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 explains the return packet (verbatim evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], hop field) and addresses edge cases like empty gaps for out-of-catalog topics. It also covers account limitations and latency, making the tool's behavior fully predictable.

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

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

Schema description coverage is 100%, with both 'question' and 'depth' already well-documented in the schema. The description adds some nuance around depth behaviors (e.g., 'gap recovery', 'chases leads') but largely repeats schema information. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources... in ONE call', explicitly distinguishing it from open-web search and from single-lookup alternatives. It also names the sibling ask_pipeworx for comparison, making the purpose unambiguous.

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

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

Provides explicit usage guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also explains when to use different depth levels (standard vs thorough), giving clear when-to-use vs 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?

Annotations already state readOnlyHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds useful behavioral context: it returns top-N tools with full schemas and curated examples, ready to call directly, and avoids a second schema lookup. 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 four sentences long and front-loaded with the core purpose ('Find tools by describing the data or task'). The domain list is long but informative, and every sentence contributes to understanding what the tool does and when to use it, with no wasted 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?

With no output schema, the description fully covers return values: it explains the response shape (top-N tools with names, descriptions, and full input schemas) and the direct-call readiness. Combined with strong annotations and 100% schema coverage on inputs, this is a complete and self-sufficient description.

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

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

Schema description coverage is 100%, so the schema thoroughly documents the 'query' parameter and its aliases plus 'limit'. The description adds the 'top-N' concept but does not introduce any parameter-specific details beyond what the schema already provides, keeping it at the baseline.

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

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

The description uses a specific verb ('Find tools') and resource (the tool catalog), and clearly distinguishes itself from sibling domain tools by being the meta-discovery tool. The domain list and 'not just one answer' contrast further clarify its unique role.

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

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

Explicit guidance is given with 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available'. It does not name specific alternative tools or when not to use it, but the instruction to call it first is clear and actionable.

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

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

The description adds significant behavioral context beyond the annotations: it discloses that the tool fans out across multiple sources in one parallel call, returns specific fields (up to 5 filings with URIs, latest 10-K fundamentals, etc.), soft-fails for patents due to the USPTO API sunset, and has a news fallback (GDELT→GNews). These are non-obvious behaviors that the readOnly/openWorld/idempotent annotations do not cover. 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 longer than average but every sentence earns its place: example queries, preference ordering, source fan-out, return fields, caveats, and input constraints are all included. It is front-loaded with natural-language examples that help an agent recognize when to invoke it. Despite being a single paragraph, there is no fluff or redundancy.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains what the agent should expect: a list of returned data types (cik, company_name, recent_filings, fundamentals, patents, news mentions, LEI). It also covers edge cases (patent API sunset, news fallback, zero-padded CIK requirement) and specifies the exact input format. For a multi-source profile tool, this is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already fully documents both parameters (type with enum 'company', value with examples and the note about names not supported). The description's mention of passing ticker or CIK and names not supported duplicates the schema exactly, adding no extra semantics beyond reinforcement.

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: building a holistic cross-source profile of a US public company. It uses specific verbs ('tell me about', 'research', 'brief me on') and lists the exact sources (SEC, XBRL, USPTO, news, GLEIF). It also distinguishes itself from sibling tools by explicitly saying to prefer it over chaining single-pack SEC/XBRL/news lookups for holistic views.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent when not to use it by stating that names are not supported and to use resolve_entity first if only a name is available. This gives clear direction on alternatives and exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the proxy fallback for blocked sources, which is valuable context beyond annotations. However, it doesn't detail normalization output or error 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?

Two tight sentences convey the core operation, a key robustness trait, and a usage pointer. 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 low-complexity fetch tool with rich annotations, the description covers the main behavior and usage. It lacks an explicit return format, but 'normalize' implies a standardized structure, and the schema examples help. Overall sufficient.

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

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

Schema coverage is 100% with clear descriptions for url, limit, and query. The description does not add parameter-level detail beyond saying 'by URL' and the examples in 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?

Clearly states the tool fetches and normalizes any RSS/Atom/RDF feed by URL, differentiating from list_feeds by recommending it for curated sources. The phrase 'any ... by URL' makes it distinct from read_feed and other 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?

Explicitly tells users to use list_feeds first for curated sources, providing clear when-to-use guidance. The CF-robust note adds context for when direct fetch might be blocked, effectively signaling a fallback behavior.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description confirms deletion and adds a privacy rationale, but it does not disclose additional behavioral details such as irreversibility or handling of nonexistent keys beyond what the annotations imply. It is consistent, not contradictory.

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 short sentences, front-loaded with the primary action, and every sentence provides useful context. 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 single-parameter delete tool with annotations covering destructiveness and idempotence, the description is adequate. It covers purpose, usage timing, and relationship to siblings. It could mention behavior on missing keys or explicit irreversibility, but annotations already hint at these, so it is nearly complete.

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

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

The schema already documents the only parameter 'key' with the description 'Memory key to delete' (100% coverage). The description's 'by key' adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Delete a previously stored memory by key.' This is specific and distinguishes it from sibling tools like remember and recall, which handle storage and retrieval.

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

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

It explicitly says when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, providing guidance on how it fits into the tool ecosystem.

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, idempotent, and non-destructive. The description adds behavioral context beyond that: it fetches the page, extracts title/description/key links, and emits standard markdown. This gives the agent a clear picture of the tool's process and output without contradicting annotations.

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

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

The description is three sentences: the first states the purpose, the second outlines the process and output, and the third gives use cases. Every sentence earns its place, with no wasted words. The most critical information 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 low-complexity tool with rich annotations and full schema coverage, the description provides sufficient context: input, process, output format, and use cases. It even explains the output is a single text blob, compensating for the lack of an output schema. No critical gaps remain.

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

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

The input schema already describes both parameters with full coverage: url and max_links with defaults and constraints. The description adds limited extra meaning (e.g., 'any URL' and 'standard llms.txt markdown format'), but the schema does the heavy lifting. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, with a specific verb ('Generate') and resource ('llms.txt file'). It distinguishes itself from sibling tools by focusing on the markdown output format and indexing purpose, making the 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 lists concrete use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI visibility. This provides clear context for when to use the tool, though it does not explicitly name alternatives or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: the feed set is 'curated' and scoped to 'space & spaceflight', and it reveals that filters are optional and that there is a handoff to read_feed for individual ids. It does not mention pagination or rate limits, but for a read-only list tool this is sufficient given annotations.

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

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

The description is compact, two sentences, with the primary verb front-loaded. Every sentence provides useful information: what is listed, optional filters, and a pointer to read_feed.

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 two-parameter optional-filters list tool with read-only annotations, the description covers purpose, parameters, and next step. It lists the returned fields in parentheses, which is sufficient given the absence of an output schema.

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

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

Schema descriptions cover both parameters (query and category) at 100%, and the description merely paraphrases them ('filter by category (space) or keyword'). No new semantic detail is added, so the baseline 3 applies.

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

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

The description clearly states the verb 'List', the resource 'curated space & spaceflight feeds', and explicitly enumerates output fields (id, title, category, source). It distinguishes from sibling tools like read_feed and list_subscriptions by positioning this as the catalog listing function.

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 says 'Optionally filter by category (space) or keyword' to indicate when filtering is applicable. The phrase 'Pass an id to read_feed' provides an explicit alternative for when a specific feed is already identified, though it doesn't fully elaborate on exclusions for other siblings like fetch_feed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the safety profile is covered. The description adds useful behavioral context: it returns the caller's subscriptions (auth scoping), includes only active ones by default, and specifies the exact fields returned. This goes beyond what annotations provide, though it doesn't mention pagination or rate limits.

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 purpose, and every sentence earns its place: one states functionality and return fields, the other gives usage context. 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 read-only list tool with one optional parameter and no output schema, the description is complete. It explains the return fields, default behavior (active only), and practical use cases, making it entirely self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a single parameter, include_inactive, which already has a clear description. The tool description aligns with that by saying 'active subscriptions' but adds no extra meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes this from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and even enumerates the returned fields (id, type, params, etc.), making the purpose unambiguous.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool in relation to subscribe/unsubscribe actions, though it doesn't explicitly name alternatives like list_feeds. The guidance is clear and actionable.

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

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

With annotations all false, the description carries the behavioral burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), how feedback is processed ('team reads digests daily'), and a constraint ('don't paste the end-user's prompt'). This is rich, useful context beyond what annotations provide.

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

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

The description is a single paragraph, moderately long, but each sentence earns its place: purpose, usage triggers, exclusions, formatting guidance, and rate limit. It is front-loaded with the core purpose. Slightly dense but not bloated.

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 feedback tool with no output schema, the description covers everything an agent needs: what it does, when to use it, what to include, restrictions, and practical details like rate limits and quota. Highly complete for its complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying how to phrase the message in terms of Pipeworx tools/packs, and it reinforces the enum semantics (bug, feature, data_gap, praise) with concrete examples. It doesn't fully compensate for all params but does add guidance beyond schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and it distinguishes from sibling tools by focusing exclusively on feedback, not on querying or research (like ask_pipeworx, deep_research).

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and when not to ('if the tool came from a different MCP server ... file it with that server instead'). It also provides a fallback for uncertainty: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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 a safe, read-only operation, but the description adds valuable context: it discloses the data source ('derived from CF analytics-engine'), privacy ('no PII'), output composition ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). This goes beyond annotation-safe defaults and paints a complete behavioral picture.

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

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

The description is three well-structured sentences with no fluff. It front-loads the core function, then gives use cases, and finally adds behavioral details. Every sentence earns its place and the formatting is easy to scan.

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

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

The tool is simple (one optional param, no required params, no output schema) and the description covers return values ('top tools, top packs, total call volume'), window options, caching, and privacy. It lacks a detailed output structure, but given the tool's simplicity and the presence of the schema, this is sufficient. Could be a 5, but the absence of a precise return format leaves a small gap.

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

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

The single optional parameter 'window' is thoroughly described in the schema (enum values and guidance on short vs long windows), achieving 100% schema coverage. The description itself does not add parameter meaning beyond what the schema already provides, so a 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 what the tool does: 'Returns the top tools, top packs, and total call volume' over a recent window, with a specific resource (Pipeworx trending data). It distinguishes itself from siblings by focusing on 'what other AI agents are calling' and explicitly lists output content, setting it apart from search or discovery 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 provides explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. These give clear context for when to use the tool, though it does not mention when not to use it or name alternatives, stopping short of a full 5.

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

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

Beyond the readOnly and idempotent annotations, the description discloses internal mechanisms: Jaccard similarity ≥0.30 semantic anchor, placeholder-fraction filter (>20% → null signal), fill-check against live CLOB depth with realizable_edge_pp ≤0 not tradeable, and a 3pp partition deviation threshold. This adds significant 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?

Though lengthy, the description is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with its primary purpose. Each sentence adds operational detail essential for correct invocation, making it appropriately sized for a complex tool.

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

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

With no output schema, the description compensates by outlining the response shape (opportunities[] fields, partition_check object) and fill-check outputs, covering edge cases (skipped_low_similarity, null arb signal, thin_legs). It is complete for a multi-mode analytical tool.

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

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

Schema coverage is 100% already, but the description enriches semantics: event takes slugs or full URLs and walks child markets; topic searches related events and flattens the union. It also clarifies how parameters relate to modes and gives concrete examples, going beyond schema descriptions.

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

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

The description clearly states the tool 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' with distinct modes (trending_scan, event, topic). It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 when to call with no args (trending_scan), when to pass `event` for a specific market, and when to pass `topic` for cross-event scanning. It also refers to polymarket_fill_risk for custom sizing and provides a 'do not trade it' warning, offering clear alternatives and exclusions.

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

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

The annotations declare the tool read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by detailing the three response segments, per-model logic, the 24h-move warning, the effect of knobs, and the caching behavior ('Cached 1h at the KV level keyed on all knobs'). No contradictions.

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

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

The description is front-loaded with a clear purpose but is lengthy and includes highly specific internal details (e.g., per-sport alpha values, funnel counters, 'gates relaxed Run 8') that may not be necessary for correct invocation. While the structure into model families and response segments aids readability, the verbosity and implementation specifics reduce conciseness.

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

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

The description covers the overall purpose, the three model families, the response top-level structure with by_segment and diagnostics, individual opportunity fields, parameter knobs, and caching. Without an output schema, this gives an agent enough context to understand what will be returned and why segments might be empty.

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 descriptions cover all 9 parameters, giving a baseline of 3. The description adds meaningful semantics by explaining how tradeable-edge knobs (min_liquidity, max_spread_pp) drop unreadable opportunities and clarifying the interaction between min_kelly and min_partition_leg_kelly for partition arbs. This adds value beyond the schema, though some parameter details (e.g., limit, window) are not further elaborated.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a clear verb+resource+outcome. It also positions the tool for the 'what should I bet on today' use case and distinguishes it from siblings by noting agents can 'discover opportunities without paging hundreds of markets.'

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 intended use case ('Built for "what should I bet on today"') and provides context about when the tool is appropriate. It does not explicitly name alternatives or provide when-not-to-use guidance, though it notes that Fed bets are excluded as unreliable, which hints at a limitation.

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 annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral context: snapshots are written on cache-miss, gaps mean no scan, history is bounded by a 60-day TTL and snapshot enablement time, and decay is computed from daily closes. It also clearly describes the response structure, including expired opportunities and median lifespan as a 'competition clock'.

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

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

The description is long but exceptionally well-structured with labeled sections (Args:, RESPONSE:, LIMITS:). Every sentence carries substantive information, and it is front-loaded with the core purpose. The length is justified by the tool's complexity and the absence of an output schema.

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

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

Given the tool's complexity and lack of an output schema, the description fully explains the response shape (tracked[], expired[], snapshot_dates[]), the meaning of each field (trend, decay_pp_per_day, lifespan_days), and important limitations (TTL, snapshot gaps, daily close computation). This is complete enough for an agent to select, invoke, and interpret results correctly.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description restates the defaults (days=14, window='1wk') and adds minor context ('snapshot family', 'lookback'), but does not meaningfully go beyond what the schema already provides.

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

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

The description states a specific function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a clear question ('how long has this edge existed and is it shrinking?') and is distinguished from the sibling tool polymarket_edges by focusing on historical persistence and decay, not just current edges.

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

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

It provides clear context for when to use: to assess whether a wide edge is fresh or stale, with the example that a 3-week-old wide edge is fundamentally different. It does not explicitly name alternative tools or say when not to use, but the intended use case is well implied.

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

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

Despite annotations already declaring the tool read-only, idempotent, and non-destructive, the description adds substantial behavioral context: it walks the order-book ladder, returns a verdict (clean/degraded/cannot_fill), and warns about forced directional risk from partial basket fills. This goes far beyond the annotation baseline.

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 dense single paragraph but front-loaded with the core purpose and free of filler. It could be better structured by separating the two modes into distinct sections, but every sentence carries useful information, so it remains efficient.

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

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

With no output schema, the description compensates by enumerating return fields for both single-market and basket modes, including top_of_book, vwap_fill_price, slippage_pp, thin_legs[], and forced_directional_risk. It also covers usage thresholds, parameter semantics, and edge-case risks, 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% and each parameter already has a detailed description (side options, size_usd meaning in both modes, default and clamp). The tool description repeats these semantics without adding new information beyond what the schema provides, so it meets the baseline but adds 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market vs basket/partition). This specific verb+resource combination differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb into an unhedged directional position), providing clear when-to-use and risk 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 declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond that by detailing the tool's internal matching logic, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and their semantics. It discloses edge cases (e.g., non-equivalent bet shapes, unrelated events) and explains what the numbers mean. This is valuable behavioral context that annotations alone do not provide.

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

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

The description is long but densely packed with essential information. It is front-loaded with the core purpose, then structured into modes, response, and safety fields, using capitalization and parentheses to improve readability. Every sentence earns its place, though some redundancy (e.g., repeating 'pre-mapped ≠ tradeable') adds a bit of length. Still, 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?

Despite lacking an output schema, the description thoroughly covers return values: leg-by-leg prices, matched spreads, compatibility_warning triggers, temporal_alignment fields, and skipped counters. It also explains the two invocation modes and the meaning of the safety fields. For a tool with no required parameters and optional overrides, this is a comprehensive description that leaves little ambiguity about input and output behavior.

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

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

The input schema already documents all three parameters with 100% coverage, setting a baseline of 3. The description adds semantic meaning by explaining the interplay between topic and the explicit override parameters: if you supply a topic, the tool auto-fetches; if you supply kalshi_event_ticker or polymarket_event_slug, they override the mapped side. This elevates the parameter understanding beyond bare 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 and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, and further outlines two distinct modes (topic shortcuts vs explicit pairings). This is far more than a vague restatement of the tool name.

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

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

The description explicitly presents two usage modes (topic vs explicit kalshi_event_ticker + polymarket_event_slug) and explains what each is for. It also warns that most pre-mapped topics currently return compatibility warnings, guiding users to prefer explicit pairings for reliable results. While it doesn't compare directly to sibling tools, the context is clear enough for an agent to know when to invoke 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by specifying the return format ('normalized items (title, link, published, summary)') and the curated nature of the feed, enhancing behavioral predictability.

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 consists of two concise sentences, with the first front-loading the core action and resource, and the second covering outputs and optional behavior. Every word earns its place, with no redundancy or tangential info.

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 operation with good annotations and a schema, the description provides all essential context: the source of feed IDs (list_feeds), the return shape (normalized items), and an optional filter. Since there is no output schema, the description fills that gap for the agent. It is complete for selecting and invoking the tool.

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

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

The input schema provides detailed descriptions for all three parameters (feed, limit, query) with 100% coverage. The description only restates the keyword filter concept without adding new constraints or format details, so it does not significantly supplement 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 ('Read'), the specific resource ('curated space & spaceflight feed'), and how to identify it ('by its id (from list_feeds)'). It also distinguishes from generic feed fetching by emphasizing 'curated' and 'normalized items', making the tool's scope clear.

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

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

The description provides clear context by indicating the prerequisite to get feed IDs from list_feeds, and mentions optional keyword filtering. While it does not explicitly name alternatives or when-not-to-use, the context is sufficient for an agent to understand when to invoke 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?

Adds valuable behavioral context beyond annotations, such as scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the ability to list all keys. Annotations already cover readOnly/idempotent/destructive hints, and the description aligns 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?

Three sentences, front-loaded with the primary action, then usage context, scope, and companion tools. Every sentence earns its place with no redundancy or 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 one-optional-parameter tool with no output schema, the description covers purpose, usage, scope, and relationships to sibling tools. It is sufficiently complete 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 description covers 100% of the parameter, but the tool description enriches meaning with concrete examples ('user's target ticker, an address, prior research notes') and clarifies the omission behavior. This adds value beyond the raw schema.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It distinguishes itself from siblings by explicitly naming 'remember' and 'forget' as companion tools.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch'. Also names alternatives (remember for saving, forget for deleting), giving clear when-to-use guidance.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description explicitly states that setting mark_read:true flags events as read so the next call shows only newer ones. This implies a persistent state change, directly contradicting the readOnly annotation. Therefore, this is an annotation 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 three sentences, front-loaded with the main action ('Pull fired events'), and includes useful operational notes (polling, alternate endpoint) without redundancy. Every sentence earns its place, making it concise and well-structured.

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

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

The description covers return payload contents, filtering options, mark_read behavior, and polling usability, which is substantial for a tool with no output schema. The contradiction slightly undermines completeness, but for a feed-read tool, it provides adequate context for basic use.

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

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

Schema description coverage is 100% for all five parameters, so the schema already documents them. The description adds a concrete example type (sec_8k) and reinforces filtering by since, but this adds minimal meaning beyond what the schema provides. 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 it pulls fired events from the subscription feed and returns recent alerts, with specific details about payload content. However, it does not explicitly differentiate itself from sibling tools like read_feed or fetch_feed, so while the purpose is clear, sibling distinction is missing.

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?

No guidance is provided on when to use this tool versus alternatives such as read_feed or fetch_feed. The mention of polling and an alternate HTTP endpoint is useful operational context, but it does not explain conditions or exclusions for choosing this tool over others.

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

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

Even though annotations already declare the tool as readOnly, idempotent, and non-destructive, the description adds substantial behavioral detail: it fans out to SEC, GDELT→GNews fallback, and USPTO with a soft-fail note for PatentsView sunset. It explains the parallel call behavior and citation URIs, going far 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 dense but every element earns its place: query examples, source breakdown with fallback logic, parameter notes, return format, and an explicit alternative. It is front-loaded with user-centric phrases and avoids 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?

With no output schema, the description fully explains return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers sources, fallback, soft-fail behavior, and parameter formats, making it self-sufficient 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 coverage is 100% with detailed parameter descriptions. The description adds extra value by giving concrete examples for `since` (ISO or '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, plus clarifying that `value` can be a ticker or CIK. While much is redundant, the typical-use guidance is useful.

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

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

The description clearly defines the tool as a change feed for a company over a recent window, with example queries that map to user intents. It explicitly contrasts with entity_profile, which handles static profile data, making the purpose unambiguous and well-differentiated from 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?

The description provides clear usage context ('what's new', 'latest on Y') and explicitly directs users to entity_profile when they need a static profile regardless of window. This gives both a when-to-use and a when-not-to-use, with a named alternative.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: key-value scope by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. No contradiction with annotations.

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

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

Four sentences, each adding distinct value: purpose, use-cases, storage model, and companion tools. No filler, efficient and front-loaded with the main purpose.

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

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

For a simple 2-parameter tool, the description covers usage, lifecycle, and scoping. Output schema is absent but not essential for a write-only operation. The combination of schema, annotations, and description provides complete context.

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

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

Schema coverage is 100%, already describing both key and value clearly. The description adds examples of keys and values but does not significantly enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses a specific verb+resource and explicitly distinguishes from sibling tools by saying 'Pair with recall to retrieve later, forget to delete'.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives (recall, forget) and explains the persistence difference between authenticated and anonymous sessions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it returns a citation URI per result, auto-disambiguates ambiguous inputs, and internally cascades through multiple endpoints. This goes beyond the annotations and helps predict behavior.

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

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

The description is well-structured: opening with user-phrase examples, then a clear directive, followed by a structured bullet list of supported types. Every sentence adds value—no fluff or redundancy. It is front-loaded and easy to scan.

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

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

The tool has no output schema and two possible type branches, yet the description explains the complete output contract for each type (including citation URI format). It also notes internal cascading behavior, which sets expectations for latency and coverage. Given the schema richness and annotations, this description is fully sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter has a description. However, the tool-level description adds substantial meaning beyond the schema: it explains the semantic difference between 'company' and 'drug' value formats, what each returns (ticker, CIK, RxCUI, etc.), and that input is auto-disambiguated. This grounds the parameters in concrete 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 verb+resource+scope: it resolves user-spoken names to canonical identifiers ('ticker', 'CIK', 'RxCUI') that other tools require. It also lists concrete example queries and supported types, making it unmistakably distinct from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also provides supported entity types and what each returns, which clarifies when to invoke this tool. The phrase 'replaces 2-3 manual lookups' reinforces its role as a preliminary lookup step.

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 value by revealing it 'probes each entity with ai_visibility_check', ranks by score, and returns specific metrics (score, confidence, signal density), which goes beyond the structured annotations.

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

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

Two sentences, front-loaded with the main purpose, and every sentence is informative. No fluff or 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?

Since there is no output schema, the description compensates by explicitly stating the return value ('ranked list with score, confidence, signal density'). It also covers the typical use case and relationship to ai_visibility_check, making it sufficiently complete for a read-only tool with strong 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% with detailed parameter descriptions, so the description doesn't need to repeat them. It adds minor context by explaining the first entity is treated as subject, but the schema already captures this. Baseline 3 is appropriate.

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

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

Description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes itself from sibling ai_visibility_check by mentioning multi-entity comparison and ranking, making the purpose unambiguous.

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

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

Provides clear context for use: 'Useful for competitive AI-marketing audits' with an example query. However, it does not explicitly mention when not to use it or directly compare to sibling tools like compare_entities, so it falls slightly short of full 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?

Beyond the readOnlyHint annotations, the description discloses fan-out behavior, performance caveats ('first measurement on a new version can take 5-30s'), graceful degradation ('sources_failed will list it if it times out, the rest still returns'), and return structure. This gives the agent a full picture of what to expect during invocation. 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 information-dense but every sentence earns its place: purpose, usage, return fields, ecosystem limit, and failure behavior. It is front-loaded with the composite check idea and logically structured, with no redundant or filler text.

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

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

With no output schema, the description fully compensates by listing the exact summary block fields, per-advisory detail, links, and alternative versions. It also covers failure modes and timing. This is complete for an agent to invoke the tool and interpret results confidently.

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, so the baseline is 3. The description adds no meaning beyond the schema: it confirms package is an npm package name and version defaults to latest, but these are already in the schema. The example 'lodash' is usage context rather than 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 opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and lists the exact data sources (deps.dev and bundlephobia) and what each contributes. This clearly distinguishes it from siblings like validate_claim or deep_research, and even notes the NPM-only scope versus other ecosystems.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a concrete alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', telling the agent when NOT to use this tool.

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

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

Goes well beyond the readOnlyHint=true annotation by detailing the output format (passages with character offsets and similarity scores), the underlying algorithm (BGE-base-en embeddings, cosine similarity over 500-char windows), and the 200K char truncation behavior with a flag. This gives the agent realistic expectations.

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

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

The description is five sentences, dense with useful information. It is front-loaded with the main purpose and each sentence contributes value (use case, output, pairing, technical details). Slightly long but not wasteful; every sentence earns its place.

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

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

Given the lack of an output schema, the description compensates by clearly stating what is returned (top-N passages, offsets, similarity scores). It also covers input constraints (200K cap), algorithm specifics, and integration with a sibling tool, making it fully self-sufficient for an agent to decide and invoke.

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 parameter descriptions are already present. The description adds meaningful context beyond the schema: it clarifies that the text is the fetched record, gives example natural-language queries, and reveals that longer inputs are truncated and flagged. This enriches the meaning of the 'text' parameter.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which clearly states the tool's action and scope. It distinguishes itself from siblings like ask_pipeworx_grounded by focusing on searching within user-provided text rather than whole documents.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also names a complementary tool (ask_pipeworx_grounded) and explains how they pair, giving clear context for selection among alternatives.

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

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

The description adds useful behavioral context beyond annotations: OAuth requirement, sms verification and 10/day cap, and type-specific parameter semantics. However, it omits the webhook delivery channel (though the schema covers it) and does not clarify idempotent semantics despite the idempotentHint=true annotation. There is no direct contradiction with any annotation.

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

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

The description is four sentences and densely packs valuable information without fluff. It front-loads the primary purpose and then efficiently covers types and delivery channels. Though slightly long, every clause earns its place.

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

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

For a tool with nested parameters, no output schema, and mixed delivery options, the description covers the essential context: types, parameters, authentication, feed, and email/sms. Minor gaps (webhook details, idempotency) are partially filled by the schema annotations, leaving the tool adequately 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?

Schema coverage is 100%, so the baseline is 3. The description adds concrete examples for each type (e.g., items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE") and clarifies delivery constraints (verified phone, cap), enriching the parameter meaning beyond raw schema definitions.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe, and enumerates supported subscription types, making the 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 clear context for when to use the tool (to establish proactive monitoring), prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist), and delivery options. It does not explicitly name alternatives like 'use recent_alerts for one-time pulls,' but the distinction is implied through the 'pull via recent_alerts' phrasing.

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

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

Beyond annotations (read-only, idempotent), it discloses important behavior: output is 'category-bucketed example questions drawn from the live catalog of thousands of tools' and that each includes tool + argument shape. This gives the agent clear expectations for the response without contradicting annotations.

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

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

The description is longer than typical, but it is front-loaded with example user phrases and structured as a single dense paragraph. Each sentence serves a purpose: explain intent, output shape, usage, and references to meta-tools. Slightly verbose but well-organized.

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

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

With a single optional parameter, no output schema, and safe annotations, the description fully covers the tool's purpose, output composition, when to use it, and parameter behavior. The agent has enough context to select and invoke the tool correctly without additional information.

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

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

The schema already describes topic and its allowed values, so coverage is high. The description adds value by explaining the default behavior (full spread without topic) and the focusing effect of passing topic, which is not fully in the schema's optional description.

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

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

The description uses a specific verb ('returns') and resource ('category-bucketed example questions... with the exact tool + argument shape'), and clearly distinguishes this from siblings like ask_pipeworx by framing it as an onboarding entry point. It answers what the tool does and why it's different.

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 tells the agent to 'Use this FIRST when you do not yet know what Pipeworx can do' and to learn how to call meta-tools, naming alternatives (ask_pipeworx, entity_profile, compare_entities). Also gives guidance on when to omit topic vs pass one.

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

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

Beyond annotations (readOnly=false, destructive=false), the description discloses that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This adds meaningful behavioral information not present in the structured data.

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

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

The description is three short, front-loaded sentences. The first states the core action, the second adds a constraint, and the third explains the effect. Every sentence contributes value.

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

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

For a simple single-parameter tool with no output schema and rich annotations, this description covers the action, constraints, and postcondition. It is complete enough for an AI agent to use 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 already fully describes the id parameter as the subscription uuid returned by subscribe. The description merely says 'by id,' adding no additional semantic information beyond the schema.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb (Cancel) and resource (subscription). It clearly distinguishes this tool from siblings like subscribe, list_subscriptions, and recent_alerts.

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: you can only cancel your own subscriptions (ownership enforced). It also explains the effect on historical events, but it doesn't explicitly mention alternatives or exclusions beyond that.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds substantial behavior: the SEC EDGAR + XBRL fast path, automatic fall-through to grounded pipeline, specific verdict categories, verbatim evidence, citation, and tolerance handling. This goes well beyond the annotations and sets expectations for how results are produced and returned.

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

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

The description is moderately long but every sentence earns its place: trigger phrases, purpose, routing logic, return values, and performance benefit. It is well-structured and front-loaded with user-intent examples, though it could be slightly tighter without losing 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?

With no output schema, the description fully covers the return format (verdicts, actual value, citation, reasoning) and explains the dual-path behavior. It gives enough detail for an agent to know what to expect and how to interpret results, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so both parameters are described in the schema. The description adds meaningful detail on tolerance_pct: its override behavior, the recommended range for hallucination detection (1–2), and the default cap at 5. This goes beyond the schema's basic description, earning above the baseline of 3.

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

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

The description clearly identifies the tool as a natural-language claim verification service, with a specific verb ('verify') and resource ('claims against authoritative sources'). It opens with concrete example queries and states the output verdict types, making its purpose unmistakable and distinct from sibling tools like deep_research 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which provides clear context for usage. It also explains the routing for company-financial vs. other claims, but does not explicitly name alternatives or state when not to use it, hence not a 5.

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