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 cover readOnlyHint, openWorldHint, and idempotentHint, lowering the bar. The description adds meaningful orchestration behavior: the tool routes to sub-tools, auto-fills arguments, and returns stable pipeworx:// citation URIs — setting expectations that this is a router rather than a direct data fetch. No contradiction with annotations.

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

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

The description is long, but front-loaded with 'PREFER OVER WEB SEARCH' and organized into preference, mechanism, triggers, examples, and exclusions. Some redundancy exists between the domain list, trigger phrases, and examples, which could be tightened, but every section earns its place for a broad open-world router 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?

There is no output schema, so the description's disclosure of the return format (structured answer with stable pipeworx:// citation URIs) is important and present. It covers what the tool does, when to prefer it, when to avoid it, which siblings to use instead, and what inputs are appropriate — nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% and the question parameter is fully documented including its aliases (query, q, prompt, text, input). The description adds value by signaling that the agent should pass natural-language questions as-is rather than structured parameters, and the six concrete examples illustrate the expected input format and scope.

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

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

The description names a specific verb and resource: it routes questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with citation URIs. It clearly differentiates itself from web search, deep_research, and ask_pipeworx_grounded, so an agent can distinguish it from siblings immediately.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and enumerates explicit trigger conditions ('what is', 'look up', 'find', 'get the latest', factual questions about real-world entities). It also states exclusions: multi-part fan-out questions should use deep_research, hallucination-resistant verbatim answers should use ask_pipeworx_grounded, and breaking-news sentiment is already routed by this tool. No usage inference is left to the agent.

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

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

Beyond the annotations, the description discloses that this is an experimental beta, that routing candidates may be enabled live, that no candidate is currently active so it matches ask_pipeworx exactly, and that it is a full router with no fallback. This is valuable dynamic-behavior context that annotations cannot capture, and it does not contradict the readOnly/idempotent/destructive 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 front-loaded with the tool's core identity, then current state, usage instruction, and a reassurance that it is fully functional. The specific date and '5,767 tools' figure are somewhat heavy, but each clause earns its place by reducing ambiguity about the beta status and behavior.

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

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

For a router tool with no output schema, the description covers identity, relationship to ask_pipeworx, current equivalence, and experimental risk. It relies on 'same response shape' rather than specifying the shape, but an agent can resolve that from the ask_pipeworx sibling. The main invocation context is otherwise complete.

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

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

Schema coverage is 100% and every parameter is described as an alias for 'question', so the description adds little semantic value. The phrase 'same arguments' confirms the signature is inherited from ask_pipeworx, but it does not explain alias priority or question formatting beyond what the schema already 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 identifies the tool as a beta version of ask_pipeworx and a 'universal router' with the same 5,767 tools, arguments, and response shape. This sets expectations and distinguishes it from the stable ask_pipeworx sibling. It lacks a crisp action verb like 'routes a question to...', but the functional role is unambiguous.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and references ask_pipeworx as the stable counterpart. This gives a clear condition for use and names the alternative. It does not spell out a hard 'when-not' or production preference, but the experimental framing makes the selection context reasonably clear.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds significant behavioral detail: it reveals the refusal mechanism, enumerates refusal reasons, specifies the exact success return shape, and discloses the extra LLM call cost. It also clarifies that the answer will come only from tool results, not from general knowledge. 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 dense but every sentence earns its place: purpose, mechanism, return/refusal contract, when to use, and cost trade-off. It is front-loaded with the most decision-relevant information and contains no filler. Although it is longer than average, the information density justifies the length.

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

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

Despite having no output schema, the description fully explains the return payload on success and the refusal payload on failure. It covers routing behavior, source scope, argument filling, cost implications, and usage boundaries. The parameter aliases are in the schema, and the annotations cover safety. Nothing needed to invoke or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description itself does not add parameter semantics beyond what the schema provides, which is expected given the high coverage. It implicitly refers to the single question parameter but does not need to elaborate further.

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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It names the exact behavior (extracts answer using ONLY what the tool result contains) and differentiates itself from ask_pipeworx by its grounded-extraction guarantee. An agent can immediately understand what this tool does and how it differs from its sibling.

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

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

The description explicitly states when to use this tool ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use it ('prefer ask_pipeworx for casual lookups'). It also names the alternative directly, ask_pipeworx, and explains the trade-off in cost. This is model usage guidance.

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

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

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?

Beyond annotations, the description discloses account/paywall requirements, latency ranges, cost scaling by depth, gap[] and contradictions[] behavior, stable pipeworx:// citations, fetched_at timestamps, and the never-invents-findings guarantee. It adds substantial 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 overly long and repetitive: grounding and not-open-web-search are stated multiple times, and stable citations/fetched_at are emphasized again near the end. It front-loads key info but many sentences restate earlier points, so not 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?

Even without an output schema, the description covers the return packet, gaps, contradictions, authentication, cost, latency, citation semantics, and source grounding. For a relatively complex tool with two parameters, nothing essential for correct invocation or expectation-setting is missing.

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

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

Schema coverage is already 100%, but the description adds real semantic value: it explains what each depth level does (quick skips gap-recovery, standard adds a second hop, thorough is paid and iterative), how depth affects price and duration, and that the question parameter supports broad natural-language decomposition. This goes well beyond the schema text.

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

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

The description states a specific action: grounded multi-source research over Pipeworx's 1506 structured data sources in one call, with facet decomposition and parallel routing. It explicitly contrasts itself with open-web search and with sibling tools like ask_pipeworx, making its identity and scope unmistakable.

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

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

The description gives explicit routing guidance: use ask_pipeworx when not signed in, use ask_pipeworx for single lookups, use ask_pipeworx_beta or ask_pipeworx_grounded for current/open-web questions, and use this tool for broad multi-part structured-data research. This is clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already 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 provides extensive behavioral detail beyond the annotations: it enumerates the fan-out sources, explains that empty sections mean real 'no data,' discloses the USPTO patents API sunset and soft-fail behavior, and clarifies the resolved:false path for private companies. It also explains that `type` accepts values interchangeably. This far exceeds what the annotations alone convey.

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

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

The description is long and dense, but nearly every sentence adds information relevant to correct invocation, and key guidance is front-loaded with examples and the 'ALWAYS PREFER' directive. The run-on semicolon-heavy structure makes it slightly harder to parse, but there is no filler. Given the tool's complexity, the length is justified.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also addresses edge cases like empty sections and private companies. The description is complete enough for an agent to call this tool correctly.

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

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

Schema coverage is 100%, but the description still adds significant meaning: it explains that 'company' and 'ticker' behave identically, gives examples for ticker, CIK, and name formats, notes zero-padding, and describes name resolution via SEC EDGAR. It also details the private-company response behavior. This is strong value beyond the schema.

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

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

The description opens with concrete query phrasings ('Tell me about X', 'research Acme') and then states the tool builds a 'full cross-source profile of a US public company in ONE parallel call.' This clearly identifies the verb, resource, and scope, and distinguishes it from chaining individual lookups. It is specific and not a tautology.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving clear when-to-use guidance. It also specifies the accepted input forms and describes the private-company fallback behavior. It does not explicitly name sibling tools like compare_entities or deep_research as alternatives, but the guidance is otherwise unambiguous.

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

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

Annotations 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?

Despite all-false annotations, the description adds substantial behavioral context: filing returns a claim_token for later status checks, the team reads digests daily, it is rate-limited to 5/day, and it is free/non-quota. It also warns not to paste end-user prompts, which is a meaningful usage boundary. 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 longer than average, but every sentence earns its place: purpose, category definitions, exclusion, token flow, SLAs, rate limits, and cost. It is front-loaded with the core purpose and structured clearly.

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 properly explains return behavior ('returns a claim_token' and later 'Returns the status and, once resolved, what actually changed'). It also addresses subtleties like nested context and the 'other' type, making it complete for a feedback 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?

Even though schema covers 100% of parameters, the description exceeds it by demonstrating the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by giving content guidance for message (be specific, no prompts). This adds real usage semantics 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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource statement that clearly defines the tool's purpose. It explicitly lists feedback categories (bug, feature, data_gap, praise), distinguishing it from sibling research/search tools.

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

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

Provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data...'). It also states a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for other MCP servers, with a disambiguation tip about tool names.

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?

Beyond the read-only/idempotent annotations, the description details compatibility codes, skipped comparison counters, fee treatment (gross not net), pairing verification limits, and null semantics for temporal alignment. This is exactly the behavioral context that helps an agent trust and interpret results.

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

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

The description is long but densely structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence carries a caveat or disclosure that matters for correct use. It could be tightened around repeated 'EITHER mode' phrasing, but the length is justified by the tool's complexity and the lack of an output schema.

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

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

With no output schema, the description carries the full burden of explaining the response shape, and it does: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped counts, fees note, and temporal_alignment semantics. An agent has enough context to call the tool and interpret results correctly.

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

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

Schema coverage is 100% and both explicit parameters already carry examples, so the baseline is 3; the description adds meaningful semantics by explaining that topic mode auto-fetches the matching event, explicit mode supports custom pairings, and both modes run the same matcher. That is value beyond the schema, though not exhaustive.

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 opening sentence names the resource precisely — the cross-venue spread between Kalshi and Polymarket for the same resolving question — and the rest states two modes. It lacks an explicit action verb and doesn't distinguish itself from sibling polymarket comparison tools by name, but an agent can infer what operation this performs.

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

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

The description gives concrete usage context: use a pre-mapped topic or explicit ticker/slug, and it warns that pre-mapped topics are often not tradeable and that bet shapes must be equivalent for the delta to be a real signal. It doesn't name an alternative sibling for cases where another venue tool is more appropriate, so it stops short of 5.

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

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

Annotations already 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?

Description discloses many behavioral traits beyond annotations: multi-source cascade (EDGAR, GLEIF, OpenFIGI), graceful degradation if GLEIF/OpenFIGI unavailable, asserting nothing when multiple matches and returning figi_candidates, and explicit unresolved identifiers. This adds substantial context beyond the readOnlyHint and idempotentHint.

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

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

The description is long and dense but every sentence adds value. It front-loads the core purpose and usage, then details supported types and edge cases. Could be slightly reorganized with bullet points, but the information density justifies the length.

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

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

For a tool with no output schema, the description thoroughly covers input formats, supported entity types, resolution behavior, edge cases, fallbacks, and result semantics. An agent has everything needed to invoke it correctly for both company and drug lookups.

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?

Although schema coverage is 100%, the description significantly enriches parameter meaning, especially for 'value' by explaining what to pass for bonds (issuer exactly as printed), what never to include (security-class words), and providing concrete examples for ticker/CIK/name and drug names. This is essential usage nuance not in the schema.

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

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

Description explicitly states the tool resolves user-spoken names to canonical/official identifiers, using specific verbs ('resolve', 'look up', 'find') and lists supported entity types. It clearly differentiates from siblings like entity_profile and compare_entities by focusing on ID lookup rather than profiling or comparison.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives detailed when-to-use examples and anti-guidance for bonds (pass issuer name only, not full noun phrase), making the selection criteria unambiguous.

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

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

Annotations 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond that: it explains the meaning of each verdict, especially the crucial distinction between "could_not_verify" (a failed check, not evidence) and "unsupported" (no source found). It also discloses the two execution paths (structured SEC EDGAR + XBRL vs. grounded pipeline) and warns callers not to treat could_not_verify as supporting or refuting a claim. 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 longer than average but every sentence contributes essential information: trigger phrases, use case, routing logic, return structure, verdict semantics, and efficiency benefit. It is front-loaded with the most important usage cues. Slight redundancy exists (e.g., "grounded pipeline" vs. "routed to the right live source"), but overall it is well-structured for the tool's complexity.

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

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

With no output schema, the description fully explains the return value: a verdict, grounded/structured value with pipeworx:// citation, and reasoning. It covers both financial and non-financial claims, explains the two distinct failure modes (could_not_verify vs. unsupported), and provides caller guidance on how to interpret the results. This is complete for the tool's complexity and no gaps are evident.

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

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

Schema coverage is 100% for both parameters, and the schema descriptions are already detailed. The description adds some context about "exact percent-delta math" and tolerance being capped at 5, which aligns with the tolerance_pct parameter, but it doesn't fundamentally expand parameter 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 identifies the tool as a claim verification resource: "natural-language claim verification against authoritative sources." It includes trigger phrases like "fact check" and "verify the claim that…" and distinguishes itself by covering both company-financial claims (via SEC EDGAR/XBRL) and any other factual claim (grounded pipeline). It also states it replaces 4–6 sequential calls, making its role unambiguous.

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

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

The description explicitly states when to use the tool: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains how it handles different claim types (financial vs. non-financial) and that it collapses a multi-step pipeline into one call. However, it does not explicitly name sibling tools to use instead or state when-not-to-use, so it falls just short of a 5.

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