sec

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful non-obvious context: the default free Workers AI model, the BYO Anthropic key with direct cost to the user, and a detailed return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

The description is three sentences: core action, default behavior/cost, return format, and use cases. It is front-loaded with the purpose and every sentence contributes new information without redundancy.

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

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

Despite lacking an output schema, the description explains the return shape and key parameters (model selection, API key, context). It covers the main behavioral nuances (free default, BYO key cost) and use cases. For a read-only tool, this is comprehensive.

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 value beyond the schema by indicating the default model (workers-ai), the cost implications of using Anthropic, and the role of 'context' for disambiguation. This extra context justifies a 4.

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

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

The description clearly states the tool probes LLMs to score visibility (0-100) per model, with a specific verb and resource. It defines the scope (business/brand/product/topic) and mentions default vs. optional models, but does not explicitly distinguish it from sibling tools like scan_competitor_ai_presence.

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

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

The description names concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass _apiKey. However, it does not explicitly mention alternative tools or when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context: the tool auto-routes to the right underlying tool, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. It does not cover failure modes or rate limits, but those are not essential given the strong annotation coverage.

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

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

The description is longer than average but front-loads the most important directive and keeps related guidance grouped into categories: data domains, trigger phrases, examples, and alternatives. Some phrasing is slightly dense and could be tightened, but each section contributes distinct value.

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

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

Given no output schema, the description adequately explains the return shape: a structured answer with stable citation URIs. It covers a broad range of factual question types, includes concrete examples, and routes the agent to alternatives, making it complete enough 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?

The input schema already provides 100% coverage, documenting 'question' and all five aliases. The description reinforces that the parameter is a natural-language request and supplies examples, but it does not add new per-parameter semantics beyond what the schema already states.

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 directive — prefer this over web search for factual questions — and names exactly what the tool does: routes the question across 5,767 tools and 1,506 verified sources, returns a structured answer with citation URIs. It also distinguishes the tool from siblings like ask_pipeworx_grounded and deep_research, making its role 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 gives explicit when-to-use guidance with trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', and 'current'. It also tells the agent to prefer this over web search even when web search could answer, and names specific alternatives for different cases: ask_pipeworx_grounded for evidence-grounded single answers and deep_research for broad multi-part questions.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important behavioral context: this is an experimental edge, candidate routing improvements may be active, it currently matches ask_pipeworx exactly, and it is a fully functional router. This gives the agent useful expectations about variability and stability 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 compact and front-loaded: it immediately states the tool is a beta version of ask_pipeworx with identical behavior, then explains the current experimental state and usage. Every sentence carries meaningful information, with no filler or repeated schema content.

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

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

Even without an output schema, the description covers the essential context: it is a full working router, accepts the same arguments, and returns the same response shape as ask_pipeworx. It also explains why an agent might select this tool over the stable sibling. It does not enumerate the 5,767 tools, but that is unnecessary for a universal router 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%, with each parameter described as an alias for 'question', so the schema already handles parameter semantics. The description adds the cross-reference that this tool accepts 'same arguments' as ask_pipeworx, but it provides no additional per-parameter detail, sticking to the baseline 3.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the same universal routing function, same 5,767 tools, same arguments, and same response shape. It also distinguishes it from the stable ask_pipeworx by describing the experimental candidate-routing edge, so an agent can tell them apart.

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 usage guidance: use it like ask_pipeworx and choose it when you want the newest routing, while noting that results are compared to the stable router. It also clarifies the current state ('no candidate active') so the agent knows it behaves identically right now. It does not explicitly discuss ask_pipeworx_grounded or state when not to use the tool, so a perfect 5 is not warranted.

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 readOnly/idempotent annotations, the description discloses the exact success return contract, the refusal_reason enumeration, the strict extract-from-result behavior, and the extra LLM call cost. 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?

Dense but front-loaded: purpose, routing, return shape, refusal cases, usage, and cost tradeoff all appear in order without filler. Every sentence adds decision-relevant information.

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

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

Given the simple one-question input and no output schema, the description fully specifies observable behavior, return shape, failure modes, and cost tradeoff. An agent can select and invoke it with high confidence.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the single required question. The description adds no parameter-specific semantics, but none is needed because the schema already fully describes the input.

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 identifies a specific mode of ask_pipeworx: a hallucination-resistant, grounded answer mode that extracts only from tool results. It also differentiates from sibling ask_pipeworx by naming the same routing and the strict grounding behavior.

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

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

Explicitly says to use when an answer will be quoted, cited, or acted on and facts must not be invented, and to prefer ask_pipeworx for casual lookups. This is direct when/when-not guidance 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description adds extensive behavioral context: response shapes, resolver contract with match confidence, parent-event extraction, news fallback behavior (GDELT 429 handling), safety short-circuits (low_confidence_match, market_closed_or_inactive), and resolution-rule risk (cancellation_rule). It discloses blocking paths, field suppression, and illiquidity warnings—far beyond annotation basics.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It front-loads the core purpose and usage in the first two sentences. While every sentence adds value, the length is substantial and could be slightly trimmed without losing critical details; a 4 acknowledges the excellent organization despite verbosity.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: result.market fields, result.analysis with model probability and edge, result.evidence, market_match_confidence, parent_event structure, news fallback fields, and cancellation_rule semantics. It also covers edge cases like low-confidence matches, closed markets, and wide spreads. The description is exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra meaning beyond the schema by providing examples for the 'market' parameter (slug, URL, question text) and describing how depth affects fan-out (quick vs thorough) with real-world examples (BTC bet → coingecko + fred + gdelt+gnews). It also explains the include_raw parameter's impact on response size, which is not fully covered by the schema's simple description.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly outlines the tool's workflow (resolve, classify, fan out, return evidence) and distinguishes it from siblings by focusing on Polymarket bet research and the 'should I bet on X' use case.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples for different market categories (BTC, Fed, Hormuz, etc.), giving clear usage context. It doesn't explicitly name sibling tools as alternatives, but the 'Use for' phrasing plus detailed examples effectively guides selection.

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

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

Annotations already provide readOnly and idempotent hints. Description adds substantial behavioral context: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with pipeworx:// citation URIs, and replaces 8-15 sequential lookups. No contradictions with annotations.

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

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

The description is longer than the minimum but every sentence adds value: trigger phrases, use guidance, type-specific details, sorting behavior, and output format. It is well-structured and front-loaded with usage intent, though slightly dense.

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 2-param tool with no output schema and strong annotations, the description covers input semantics, data sources, sorting, and return format (paired data + citation URIs). It also explains the efficiency advantage, making it sufficiently complete 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 covers 100% of parameters with descriptions and examples. Description adds meaning by explaining type-specific data pulls (company: 10-K financials; drug: FAERS/FDA/trial counts) and clarifying values as tickers/CIKs or drug names beyond schema. This adds value beyond the schema.

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

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

Clearly states side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and resource types. Distinguishes from sequential single-pack lookups and says ALWAYS PREFER, making its purpose and advantage explicit.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases ('X vs Y', 'which is bigger'). This clearly indicates when to use and implies when not to (for single entity lookups).

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

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

Beyond the readOnly/openWorld/idemotent hints, the description discloses account and paid-tier requirements, parallel routing across 5,767 tools, gap[] behavior that never fabricates findings, citation_uri fetchability conditions, contradictions[] for standard/thorough, semantic excerpting, and latency ranges. This is comprehensive and does not contradict 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 front-loaded and information-dense, but several sentences repeat schema content (the depth semantics) and ask_pipeworx is recommended twice. The dense wall of text could be streamlined without sacrificing the valuable operational details.

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

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

With no output schema, the description thoroughly describes the findings packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]) and the full calling context (auth, pricing, latency, source coverage). Nothing critical for correct invocation or interpretation is missing for a tool this complex.

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

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

The schema already covers both parameters at 100% and gives a detailed explanation of depth levels; the description mostly reiterates that content (e.g., standard does gap recovery, thorough chases leads). It adds minimal new parameter-level meaning, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb-resource pair: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources'. It also draws a boundary against open-web search and names ask_pipeworx as the single-lookup sibling, so the tool is clearly differentiated.

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

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

It gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), and an auth-based exclusion ('If you are not signed in, use ask_pipeworx instead'). Alternatives are named and conditions are 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=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds context about what the agent receives and that no further lookups are required.

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

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

The description is front-loaded with the core purpose and includes a long but informative list of domains. It contains four sentences, each serving a purpose (purpose, when to use, return behavior, priority guidance). The domain list is slightly verbose but valuable for an agent to understand the tool's coverage.

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 discovery tool with no output schema, the description does a strong job explaining what it returns (tool names, descriptions, full input schemas with examples) and that results are directly callable. It also covers intended usage contexts. Minor gaps include not specifying how results are ranked or whether search is limited to the current toolset, but these are inferable.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters, including aliases and the limit. The description only adds the 'top-N' concept, which is already reflected in the limit parameter's schema description. Thus it meets the baseline, but does not add significant meaning beyond the schema.

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

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

The description opens with 'Find tools by describing the data or task,' which is a specific verb+resource definition. It clearly distinguishes the tool from sibling tools as the discovery/meta tool, especially with the explicit 'Call this FIRST' guidance.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for...' and provides a comprehensive list of domains. It also instructs to call it first when many tools are available, effectively telling the agent when not to use alternative tools.

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

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

Annotations already mark the tool readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond by disclosing fan-out sources, specific return fields, the USPTO API sunset soft-fail, the FDA products expected-empty case, and the explicit 'sources_used/sources_failed' semantics distinguishing genuine no-data from bugs. This is exactly the behavioral context an agent needs.

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

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

The description is long, but every section earns its place given the tool's complexity: example triggers first, then source fan-out, then return shape, then edge cases. It is front-loaded with the core purpose and structured with clear paragraphs, though a slightly tighter list of return fields would improve scannability.

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

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

Even without an output schema, the description enumerates the full return shape (cik, resolved_from/to, recent_filings with URIs, fundamentals, patents, contracts, fda_products, hiring, news, LEI, sources_used/failed), plus parameter flexibility and edge-case behavior. For a tool with this many data sources and failure modes, nothing an agent needs to invoke and interpret results is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it states that 'type' values are interchangeable, that 'value' can be a ticker, CIK, or company name, and that names resolve via SEC EDGAR's company-name match. It also gives concrete examples (AAPL, 0000320193, Moderna) and clarifies the private-company resolved:false behavior, which hugely helps the agent select and format inputs.

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

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

The description opens with concrete user-phrase examples and then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource ('US public company'), the verb ('profile'), and explicitly contrasts itself with single-pack SEC/XBRL/news lookups, which cleanly differentiates it from siblings like get_company_facts and get_company_filings.

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

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

It gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers edge cases (private companies, name resolution, expected empty sections), telling the agent precisely when this tool is appropriate and what conditions change 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?

The annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about the type of data (sensitive data saved earlier) and that the action is a deletion, which is consistent with the annotations. It does not go into further behavioral detail like irreversibility, but with annotations covering the main traits, this is adequate.

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

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

Two sentences deliver purpose and usage without filler. Every clause contributes meaningful information, and the text is appropriately front-loaded with the action.

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

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

For a one-parameter destructive tool, the description provides purpose, usage context, and sibling relationships. Annotations cover destructive and idempotent behavior, and the schema fully describes the parameter. No output schema exists, so return value documentation is not expected. The description is sufficient 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?

The schema has 100% coverage of the only parameter, 'key', described as 'Memory key to delete.' The description reinforces that the key identifies the memory but doesn't add new semantics beyond the schema. This meets the baseline for high schema coverage.

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

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

The description opens with 'Delete a previously stored memory by key' — a specific verb and resource that clearly distinguishes it from siblings like remember (store) and recall (retrieve). The name 'forget' reinforces the delete semantics, making the tool's 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 second sentence provides explicit usage scenarios: '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,' which guides tool selection. No explicit 'when not to use' is given, but the positive guidance is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral detail beyond annotations: it fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt markdown format. This explains the process and output without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence earns its place: purpose, process, and use cases. No redundant wording 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 simple two-parameter tool with a clear output (a text blob) and strong annotations, the description covers what the tool does, how it does it, and when to use it. No output schema exists, but the description sufficiently explains the return value's nature and format.

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

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

Schema coverage is 100% (both 'url' and 'max_links' have descriptions). The description does not specifically detail the parameters but implies the URL is fetched and links are extracted. Since the schema already covers parameter meaning, a baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource construction ('Generate a production-ready llms.txt file for any URL') and clearly distinguishes itself from siblings by focusing on the act of generating the file itself, versus tools like 'scan_competitor_ai_presence' or 'ai_visibility_check' which likely just assess visibility.

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

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

The description provides three concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor. This gives clear context for when to use the tool. It does not explicitly mention alternatives or exclusion criteria, but the use cases strongly imply the intended scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description then adds substantial behavioral context beyond that: results are resolved to the filer's currently reported XBRL concept, every figure carries fiscal year and period end, and retired concepts are kept for history but flagged stale and sorted last. These are exactly the non-obvious behaviors an agent needs to interpret results correctly.

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

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

Two sentences with the core purpose front-loaded first. The metrics list and the concept-resolution/stale-sorting behavior each earn their place; there is no filler or repetition of schema content beyond the brief input-method mention.

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

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

For a single-parameter tool with an output schema present and annotations covering safety, the description is complete: it explains what is returned, the fiscal-year scope, the concept-resolution nuance, and how retired concepts are surfaced. Nothing an agent needs to correctly select and invoke the tool is missing.

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

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

Schema coverage is 100%, and the single 'cik' parameter's schema description already documents accepted inputs (CIK, ticker, name) and the auto-resolution behavior. The description restates this at a high level but adds nothing beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: "Get XBRL financial facts for a company by CIK number, ticker, or company name." The domain specificity (XBRL, latest_annual, 10-K, specific metrics) makes it unambiguous against siblings like get_company_filings (documents) and entity_profile (profile data).

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 of use: an agent needing a company's most recent fiscal year financial figures (revenue, net income, EPS, etc.) would select this tool. The 10-K framing and concept-resolution behavior further sharpen when it applies. It stops short of explicit when-not-to-use guidance or named alternatives, so it doesn't reach 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the tool's non-destructive nature is known. The description adds useful behavioral context: it returns filing dates, form types, and accession numbers, and supports filtering by form type. It does not define 'recent' precisely, but with annotations covering safety, this is sufficient.

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

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

Two concise sentences, front-loaded with the core action and resource, followed by return fields and optional filtering. No redundant phrases or filler; every word adds value.

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

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

With a full input schema, output schema, and informative annotations, the description covers all essential aspects: purpose, flexible input, optional filtering, and return data. For a low-complexity read-only tool, this is complete.

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

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

Schema coverage is 100%, and both parameters (cik and form_type) are well documented in the schema itself, including auto-resolution of ticker/name. The description largely reiterates this information rather than adding new semantic detail, so it meets the baseline but doesn't exceed it.

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: retrieving recent SEC filings for a company, with explicit mention of flexible identifiers (CIK, ticker, company name) and optional form-type filtering. This distinguishes it from siblings like get_company_facts and search_companies, 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 conveys a clear use case: when you need recent SEC filings for a company with specific returned fields and optional filtering. It does not explicitly name alternatives or exclusions, though the sibling context (e.g., get_company_facts) implies a different purpose, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds worthwhile behavioral detail beyond that, including the scope (caller's subscriptions), the default active-only filter, and the specific fields returned. This enriches the agent's understanding of what to expect.

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 main function, the second lists return fields, and the third gives usage guidance. It is front-loaded, concise, and every sentence contributes value without redundancy.

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

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

For a simple list tool with one optional parameter, rich annotations, and no output schema, the description covers purpose, scope, return format, and use case. The schema fully handles parameter semantics, so nothing important 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?

The input schema fully describes the single parameter (include_inactive) with a clear description and default value. The description only reinforces the active-only default by saying 'active subscriptions' but does not add meaning beyond the schema. Baseline 3 is appropriate under full schema coverage.

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

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

The description clearly states the tool's action ('List') and resource ('the caller's active subscriptions'), and also enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This differentiates it from sibling tools like subscribe and unsubscribe, which perform different actions.

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 implies when to use the tool and indirectly points to alternatives (subscribe/unsubscribe), though it does not name them explicitly 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 only indicate non-readOnly/non-destructive, leaving room for the description to explain behavioral nuance. It does so thoroughly: explains the claim_token mechanism for later retrieval, rate limits (5/day), that it's free, doesn't count against quota, and that the team reads digests daily. This goes well beyond annotation hints and sets clear expectations for the side effects of filing feedback.

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?

Despite being long, the description is front-loaded with purpose, then logically progresses through usage boundaries, message guidance, claim token flow, and rate limits. Every sentence adds unique value; there is no fluff or redundancy. The structure makes it easy for an agent to parse and act on.

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

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

The tool has no output schema, but the description compensates by explaining return values (claim_token, status of prior reports) and the overall feedback workflow. It covers all necessary contextual elements: types, exclusions, message expectations, account handling, and operational constraints, making the tool fully self-contained for an agent.

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

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

Even though schema descriptions cover 100% of parameters, the description adds significant context: it maps the 'type' enum values to real-world scenarios ('bug', 'feature', 'data_gap') and explains the claim_token usage pattern (pass it back alone to retrieve status). This gives the agent deeper understanding of how to construct calls beyond what the schema 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 uses a specific verb ('Tell'), identifies the resource ('Pipeworx team'), and clearly distinguishes this from sibling tools by framing it as feedback (broken, missing, needs to exist). It lists concrete feedback categories, making the tool's purpose unmistakable and differentiated from query/analysis tools.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... a tool you wish existed...'), and provides an important exclusion: only for tools served by this Pipeworx connection, not other MCP servers. It also gives actionable guidance on how to describe issues (in terms of Pipeworx tools, not end-user prompts), which serves as effective usage direction.

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

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

Annotations already establish read-only/idempotent safety, but the description adds meaningful behavior beyond that: it's self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h. This gives the agent crucial expectations about freshness and privacy.

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, front-loaded with the core value proposition, and uses a numbered list for use cases. Every sentence provides distinct information: purpose, outputs, use cases, data provenance, privacy, and caching. 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?

For a simple read-only analytics tool with one optional parameter, the description covers purpose, use cases, output composition, privacy, cache behavior, and window semantics. The lack of an output schema is mitigated by explicitly listing what is returned. This is complete.

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

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

The schema covers 100% of the single parameter and its enum, but the description adds interpretive value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent reason about which window to choose beyond the raw 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 opens with a specific verb+resource: 'What other AI agents are calling on Pipeworx right now' and explicitly lists the outputs (top tools, top packs, total call volume). This clearly distinguishes it from siblings like discover_tools, which is about broader tool discovery.

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

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

The 'Useful for' section enumerates three concrete scenarios (hot data sources, canonical tool confirmation, alignment with agent needs) and explains window choice across short vs. longer lookbacks. It lacks explicit 'when not to use' or alternative tool names, but the context is strong.

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

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

Annotations already declare readOnly, non-destructive, and idempotent. The description goes far beyond by explaining the fill check (realizable_edge_pp <= 0 means 'do not trade it'), the semantic anchor threshold (≥0.30 Jaccard), the partition filter, and the exact response structure. No contradictions with annotations.

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

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

Though long, the description is dense and well-organized. It front-loads the core purpose, uses semicolons and parentheticals to group related details, and every sentence earns its place. The clear progression from modes to filters to response to fill check makes it easy to parse.

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

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

With no output schema, the description compensates by specifying the response fields (opportunities[], gap_pp, partition_check, suggested_trade, etc.). It covers all essential aspects of the tool: modes, edge cases, filters, safety checks, and cross-tool references. Nothing crucial 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 covers 100% of parameters with solid descriptions, but the description adds crucial context beyond it: the no-args mode (trending_scan) isn't in the schema, event is recommended for specific markets, and topic is explained with the flattening/union comparator behavior. This enriches the parameter meaning significantly.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by naming its unique mechanisms and output.

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 explains three calling modes (no args, event, topic) with concrete examples and a recommendation ('event (recommended for a specific market)'). It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: detailed model family mechanics (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio'), edge computation net of slippage, Kelly caps, the 24h-move warning, partition filter rules, and response diagnostics. It also discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'). No contradictions with annotations.

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

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

The description is long but well-structured: one-sentence summary, then segment explanations, response fields, knobs, diagnostics, and caching. It contains specific constants (e.g., 'tennis 1.02, soccer 1.10, MMA 1.15') and conditionals ('partitions with >20% placeholder fraction skipped entirely') that earn their place. It is dense but not redundant; could be trimmed for quicker scanning, but complexity 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 no output schema, the description thoroughly describes the response shape: 'by_segment{model_driven,structural_arbitrage,concentrated_longshot}', diagnostics with funnel counters, and top-level fields like fed_candidates/fed_note. It also explains why a segment might be empty ('top-N stale, all candidates failed gates, knob dropped them') and the caching key. This is unusually complete for a tool of this complexity.

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

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

Schema coverage is 100% (all 9 parameters have descriptions), so baseline is 3. The tool description adds meaning beyond the schema by explaining the strategic purpose of the 'TRADEABLE-EDGE KNOBS' and clarifying subtle behaviors like min_partition_leg_kelly applying to per-leg Kelly inside top_legs. It does not restate each parameter's type/format but provides higher-level filter logic, which is valuable.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_fill_risk by focusing on model-driven edge discovery across top 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" — agents discover opportunities without paging hundreds of markets.' It also explains when knobs like min_liquidity/max_spread_pp should be used ('set to 2 to require tight books') and why Fed bets are excluded. However, it does not explicitly name alternative tools or say 'use X instead,' so it lacks the when-not guidance of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description adds rich behavioral context: how snapshots are written (cache-miss), why snapshot gaps occur, the 60-day TTL limit, and that decay is computed from daily closes rather than intraday. It also explains the meaning of expired opportunities and the 'competition clock' concept.

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 informative, with clear structural labels (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence adds value, explaining response fields and operational limits without redundancy.

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

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

With no output schema, the description thoroughly explains all return fields (tracked[], expired[], snapshot_dates[]) including sub-fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It also covers limitations (TTL, data gaps, daily vs intraday), making it complete for the tool's complexity.

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

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

The input schema already provides full descriptions for both parameters (days, window) with defaults and ranges. The description repeats defaults ('default 14, max 30', 'default 1wk') but adds minimal new semantics like 'snapshot family' and cache-miss behavior. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling polymarket_edges by focusing on the temporal dimension of edges rather than current snapshots.

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

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

The description implies when to use the tool by explaining the use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and describing what the response contains (tracked, expired, snapshot_dates). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it over polymarket_edges.

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 destructiveHint=false, but the description adds substantial behavioral context: it walks the order-book ladder, compares top-of-book vs VWAP, reports per-leg fill details, and flags 'forced_directional_risk' legs. It also discloses the failure mode of partial fills converting an arb into directional position—information beyond the annotations that is critical for safe use. No contradiction with annotations.

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

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

The description is long but well-structured with SINGLE-MARKET and BASKET sections, and it is front-loaded with the core purpose. Every sentence carries operational detail—no filler—but the density may make it slightly heavy for quick scanning. It earns its length given 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 and a complex two-mode tool, the description enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific outputs). It also names edge cases like thin_legs and forced_directional_risk, and explains how to interpret the results in the broader arbitrage workflow. This is fully complete for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, but the description adds important interpretive value: it explains the mutual exclusivity of market vs event ('REQUIRES one of...'), clarifies size_usd semantics per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional'), and defines the auto default for basket side. This goes beyond the bare schema field descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely identifies the tool's function. It also distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by framing itself as the pre-trade verification step for those signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides the rationale—theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk—which clarifies when it is necessary and why alternatives are insufficient on their own.

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

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

Annotations already mark the tool as read-only and idempotent, so the bar is lower, but the description adds substantial behavioral context: compatibility warnings can be non-empty even when pairs are returned, `pairing_unverified` is always set, spreads are gross not net, Kalshi fees are not modeled, and unknown legs are never paired. It also explains the meaning of `temporal_alignment` null values, which prevents misinterpretation.

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 tightly organized with labeled sections like 'TWO MODES,' 'RESPONSE,' 'SAFETY FIELDS,' and 'Codes,' making dense information navigable. It front-loads the core purpose and then layers warnings and caveats that are genuinely necessary for correct use of a spread-comparison 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 must carry the burden of explaining the response shape, and it does: leg-by-leg prices, `top_spreads_pp`, `compatibility_codes[]`, `skipped_unclassified`, `low_confidence_pairs[]`, `temporal_alignment`, `fees_note`, and skip counters. It also covers edge cases like unknown legs and null alignment, making the tool safely callable without external documentation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds important semantics beyond that: `topic` auto-fetches matching events from both venues, explicit ticker/slug overrides apply per venue, and both modes run the identical token-overlap matcher. This extra meaning helps an agent decide which parameter combination to use.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes itself from siblings by focusing on cross-venue comparison and explains the two modes, `topic` and explicit ticker/slug, which fully clarifies what the tool does.

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

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

The description clearly explains the two invocation modes and warns that 'pre-mapped ≠ tradeable,' which gives implied context for when the tool is appropriate. However, it never explicitly names alternatives like `polymarket_arbitrage` or `polymarket_edges`, nor states conditions for choosing this tool over them.

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

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

With readOnlyHint and idempotentHint annotations already covering safety, the description adds valuable context about scoping ('anonymous IP, BYO key hash, or account ID') and explains the list behavior when no key is given. It does not mention edge cases like missing keys, but the annotation coverage lowers the bar.

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

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

The description is front-loaded with the main action, and each subsequent sentence adds unique value: use case, scoping, and relationship to sibling tools. Despite being slightly longer than a minimal description, every sentence earns its place and there is no wasted wording.

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 retrieval tool with one optional parameter and no output schema, the description is complete. It covers the two modes (get by key, list all), explains the scoping model, and provides usage context. Combined with the rich annotations, an agent has all necessary information 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?

The schema fully documents the single 'key' parameter (100% coverage), so the description adds little beyond what's in the schema. The examples of key contents ('user's target ticker, an address, prior research notes') are illustrative, but not necessary for understanding the parameter itself.

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 ('retrieve') and resource ('value previously saved via remember'), and clearly distinguishes the list-all-keys behavior when the key is omitted. This is precise and differentiates from sibling tools like remember and forget.

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

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

It explicitly tells when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and names the complementary tools for saving and deleting ('Pair with remember to save, forget to delete'). This serves as both positive and negative 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes further by revealing the mark_read side effect that advances the feed, describing the return payload (source, citation_uri, raw event payload), and noting the feed is persisted. This adds meaningful behavioral context beyond what annotations provide, though it doesn't cover auth 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?

Three sentences efficiently deliver the core purpose, return details, filtering, stateful behavior, and polling advice. It is front-loaded with the main verb and resource, and every sentence earns its place without verbosity.

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

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

With no output schema, the description appropriately summarizes the return payload. It covers filtering, mark_read side effects, and polling suitability. Combined with the 100% schema coverage for parameters, it gives a complete picture of how to use the tool, though it leaves potential error conditions and rate limits undisclosed.

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

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

Schema coverage is 100% and each parameter has a clear description. The description adds value by providing a concrete example for type ("sec_8k"), clarifying since as an ISO timestamp, and explaining the practical consequence of mark_read (next call only shows newer events). It doesn't add material meaning for limit or unread_only, but the schema already handles those well.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource pairing. It then clarifies it returns alerts the evaluator has written, distinguishing it from sibling tools like list_subscriptions (which manages subscriptions) and recent_changes (which tracks other changes). The purpose is unmistakable.

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

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

The description indicates when to use it (to retrieve alerts from a subscription feed) and states polling is fine, even suggesting an alternative HTTP endpoint for scripts/dashboards. It does not explicitly name sibling alternatives, but the context clearly implies this is the tool for reading fired events, while siblings like list_subscriptions serve different purposes.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable behavioral context: source-specific fallback mechanics, a USPTO soft-fail due to PatentsView sunset, and the return structure (changes[], total_changes, pipeworx:// citation URIs). No contradiction with annotations.

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

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

The description is dense yet well-structured: it front-loads trigger phrases, then explains sources, supported formats, return values, and alternatives. Every sentence earns its place, with no filler or redundancy.

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

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

Despite having no output schema, the description specifies return grouping, total count, and citation URIs, plus fallback and sunset behavior. It covers the complexity of a multi-source fan-out and gives an explicit alternative for static profiles, making it sufficient for a complex 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%, so the schema already documents all three params. The description adds practical guidance (relative shorthand examples, 'Use 30d or 1m for typical monitoring', ticker vs CIK) that enriches schema understanding without fundamentally transforming it.

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

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

The description clearly identifies a change-feed tool for companies over a date window, with natural-language triggers and explicit fan-out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling entity_profile tool by contrasting dynamic changes with a static profile.

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

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

It provides explicit when-to-use signals via example queries ('What's new...') and a direct alternative: 'Use entity_profile instead when you want the static profile...' It also documents fallback behavior (GDELT→GNews) and accepted input formats, giving clear invocation 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 cover idempotency and non-destructiveness, but the description adds crucial context about scope (by identifier), persistence differences (authenticated vs. anonymous 24-hour retention), and the key-value storage format. This goes beyond the annotations, though it stops short of specifying overwrite semantics or error handling.

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

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

Three sentences, front-loaded with the main purpose, and each sentence adds distinct value: what it does, when to use it, and how it stores data. No filler or redundancy.

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

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

For a simple two-parameter tool with no output schema and helpful annotations, the description covers all essential aspects: functionality, usage triggers, persistence behavior, and tool relationships. It is complete and self-sufficient for an agent to select and 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?

Schema already provides 100% parameter coverage with descriptions, so baseline is 3. However, the tool description adds meaning by explaining the key-value pairing and 'scoped by your identifier', which helps the agent understand how parameters interact and why uniqueness matters. The example keys ('subject_property', 'target_ticker') further clarify expected values.

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 'Save data the agent will need to reuse later', with a specific verb and resource (memory). It distinguishes itself from siblings by explicitly mentioning pairing with 'recall' and 'forget', making its role in the persistent-memory lifecycle unambiguous.

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

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

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and names complementary tools ('Pair with recall to retrieve later, forget to delete'), which frames the correct context for usage versus 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 (readOnlyHint, idempotentHint, destructiveHint) are all true/non-destructive, and the description adds substantial behavioral context beyond these: internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit handling of unresolved identifiers, and matching behavior for non-equity instruments. No contradictions exist.

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

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

Although long, the description is densely informative and front-loaded: the first two sentences establish purpose and use-case, followed by structured detail for each type. Every sentence adds operational knowledge (examples, warnings, degradation behavior) with zero repetition. The length is justified by 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 must explain return values, which it does: it lists the identifiers returned for each type (CIK, ticker, LEI, FIGI; RxCUI, ingredient, brand), mentions the 'unresolved' field and 'figi_candidates' for ambiguous matches, and notes citation links for drugs. It also covers fallback behavior when external services are down. This is complete for an agent to call and interpret results.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema. For 'value', it gives concrete examples (AAPL, CIK, brand names) and warns about passing exact issuer names vs. full noun phrases, a critical subtlety. For 'type', it details exactly what each enum value resolves to (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand). This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates example queries, lists supported types (company, drug), and explicitly differentiates from siblings by instructing 'Use FIRST whenever you have a name but need an ID.' This is a precise verb+resource statement that distinguishes it from broader 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?

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), provides concrete example queries, and explains the trade-off (replaces 2-3 manual lookups). It also clarifies edge cases (e.g., ambiguous matches return figi_candidates, unresolved IDs are placed under 'unresolved'), making the selection condition 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 indicate read-only, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds valuable context about the internal process: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and describes output fields ('score, confidence, signal density'). This goes beyond annotations without contradicting them.

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

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

The description is concise, with two sentences that front-load the core purpose and provide a concrete use case and output summary. Every sentence adds value, with no redundant repetition of schema or annotations.

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

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

Given the tool's complexity (multi-entity comparison, optional models and API key), the description covers the purpose, process, use case, and return values. The schema handles parameter details, and the description fills in the behavioral and output context. It lacks explicit mention of models or API key behavior, but those are documented in the schema, so it is sufficiently 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 provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description reinforces the entities parameter by explaining 'your brand + N competitors' and mentions the probing mechanism, but it does not add new details beyond the schema. It is adequate but not additive.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'Compare', the resource 'AI visibility', and the multi-entity scope, which distinguishes it from the sibling tool ai_visibility_check that focuses on a single entity. It also details the workflow (probe, rank, surface) and output, leaving no ambiguity.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' and offers an illustrative example question. It implies this tool is for comparative scenarios, contrasting with single-entity checks, but does not explicitly state when not to use it or name alternatives. This is strong contextual guidance, though missing explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description goes beyond annotations by disclosing partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts), the non-atomic nature across sources, and the exact return summary fields. This adds significant behavioral context 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?

The description is long but information-dense, with a clear progression: purpose, usage triggers, return fields, ecosystem scope, and failure modes. Every sentence contributes unique value for a composite tool. It is not overly verbose given the complexity, though it could be tightened slightly without losing critical 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?

With no output schema, the description carries the full burden of explaining the return payload, and it does so thoroughly: it lists the summary fields, per-advisory details, links, and alternative versions. It also covers timeout behavior, partial failures, and ecosystem limitations. For a tool of this complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, with both 'package' and 'version' well-documented in the schema. The description adds marginal value by framing 'version' as optional and defaulting to latest, and by mentioning scoped packages, but this is largely redundant with the schema. The description doesn't add deeper parameter-level semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for 'should I add this npm package' and explicitly lists the data sources (deps.dev, bundlephobia) and the decision context. It distinguishes itself from siblings by being the only npm package evaluation tool, with a specific verb and resource ('scan' + 'dependency').

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 trigger conditions ('whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"') and also gives an explicit exclusion/alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is excellent guidance for tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context by specifying the return format (company names and CIK numbers) and the tool's role in the workflow, 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?

The description is two sentences, front-loaded with the action and resource. The first sentence states what the tool does; the second explains the output and workflow context. Every word contributes value, 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 simple single-parameter tool with rich annotations and an output schema, the description is sufficiently complete. It covers the purpose, input type, output, and the critical workflow context (CIK needed for other SEC tools), enabling an agent 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 input schema provides a comprehensive description of the single 'query' parameter, including examples ("Apple", "TSLA"), covering 100% of parameters. The description's mention of 'name or ticker symbol' essentially restates the schema, adding no additional parameter nuance, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Search SEC EDGAR'), the resource (companies), and the input type (name or ticker symbol). It also describes the output (company names and CIK numbers) and explicitly connects this to other SEC tools, which distinguishes it from siblings that consume CIK numbers.

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

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

The description implies the primary use case by noting that CIK numbers are 'needed for other SEC tools,' establishing this as the entry point for SEC data retrieval. It does not explicitly name alternative tools or state exclusions, but the context is clear given the sibling tool names like get_company_facts and get_company_filings.

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 behavioral traits beyond annotations: it details the internal mechanics (BGE-base-en embeddings, cosine over 500-char overlapping windows), the truncation cap at 200K chars with flagging, and the output structure (character offsets and similarity scores). Since annotations already cover read-only safety, this added depth is highly valuable.

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 core action, followed by usage guidance and technical details. Every sentence adds new information—purpose, value proposition, and caveats—without repetition or fluff.

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

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

Despite lacking an output schema, the description fully prepares the agent by explaining the return format (passages with offsets and scores), the ideal use case, the truncation behavior, and the recommended workflow with a sibling tool. It covers all necessary operational details for a tool with this complexity.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds meaningful context beyond the schema by giving concrete examples for 'text' (SEC 10-K body, article, long tool result) and noting that longer inputs are truncated and flagged. This adds practical semantics not in the schema, earning a 4.

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

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

The description uses a specific verb and resource: 'Semantic search INSIDE a fetched record' with the return of 'top-N passages with character offsets and similarity scores.' It clearly distinguishes from sibling tools like search_companies and explicitly connects to ask_pipeworx_grounded, making the tool's 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?

It provides explicit usage context: 'Use when the record is too big to cram into the prompt' and describes a pairing with ask_pipeworx_grounded for a two-step workflow. It also explains the benefit (saves context, returns only relevant passages) without needing to formally list 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 substantial behavioral context beyond the annotations: it states the return value (new subscription id), the auth requirement, that anonymous/BYO cannot persist, the always-on feed behavior, SMS verification and cap, and the ability to pull alerts via recent_alerts. This goes far beyond the readOnlyHint/idempotentHint annotations and fully discloses operational traits.

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

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

The description is moderately long but densely packed with essential information. It is front-loaded with the main purpose, followed by auth requirement, supported types, and delivery channels. The structure is logical and mostly concise, though the delivery section is lengthy and could be more compact without losing key details.

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

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

For a tool with 3 parameters and nested objects, the description covers the return value, auth prerequisites, supported types, and delivery options. It omits webhook in the main text, but the schema fully documents it. The description is complete enough for an agent to correctly select and invoke the tool, with the schema filling in the remaining parameter details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description gives examples for sec_8k, polymarket_edge, and fred_series, but these closely mirror the detailed schema descriptions for the 'params' property. The delivery channels are also described similarly to the schema. Thus, the description does not add significant semantic value beyond the structured 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 primary action with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by explicitly focusing on the creation action. The supported subscription types and delivery channels further clarify its scope.

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

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

The description provides context on when to use the tool (for proactive monitoring) and notes an important prerequisite (requires a Pipeworx OAuth account). It also hints at an alternative for non-persistent retrieval via 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json', though it doesn't explicitly name sibling tools as alternatives. This is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it returns category-bucketed examples drawn from a live catalog, includes tool+argument shapes, and supports optional topic filtering. It doesn't contradict annotations.

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

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

The description is longer than average, but every portion earns its place: user-phrasing examples, the purpose, return value, usage variants, and explicit first-use guidance. It is front-loaded with natural-language queries and organized with em-dashes and parentheticals. Slightly dense but not wasteful.

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 explains what the tool returns (category-bucketed example questions with exact tool+argument shape), how to call it (no args vs topic), and when to use it. Given the light schema and strong annotations, this is sufficient and 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?

The schema already documents the single optional topic parameter with 100% coverage. The description adds extra semantic value by giving example values ("finance", "pharma", "betting") and clarifying the behavior difference between omitting and providing the topic — omit for a cross-category spread, pass topic to focus. This goes slightly beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It also distinguishes itself from sibling tools by explicitly noting it should be used FIRST and that it teaches how to call meta-tools like ask_pipeworx and entity_profile.

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

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

The description gives explicit usage guidance: call with no arguments for the full spread, pass topic to focus, and use FIRST when you don't know what Pipeworx can do. It also points to alternatives (meta-tools) and lists concrete example topics, making when-to-use unmistakable.

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

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

The description adds meaningful context beyond the annotations: ownership enforcement, deactivation rather than deletion, and historical events remaining available via recent_alerts. These details are not captured in the annotations and provide useful behavioral transparency.

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

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

The description is two sentences, front-loaded with the core action. Every phrase adds value: ownership, deactivation, and historical availability. There is no unnecessary verbosity.

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

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

The tool is simple (one parameter), and the description covers key aspects: cancellation, ownership, deactivation, and historical availability. The lack of output schema and return value explanation is a minor gap, but given the low complexity, the description is largely complete.

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

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

The schema already fully describes the id parameter (coverage 100%), noting it is returned by subscribe. The description only says 'by id,' adding no new meaning, so it meets the baseline of 3.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb and resource. It clearly distinguishes this tool from siblings like subscribe and list_subscriptions by the action, and the mention of deactivation further clarifies the exact effect.

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

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

The description clearly states the tool cancels a subscription and imposes an ownership constraint ('you can only cancel your own subscriptions'), which informs when to use it. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations declare readOnly/openWorld/idempotent, but the description adds critical behavioral nuances: the distinction between two processing paths, exact percent-delta math for company financials, and the crucial semantics of 'could_not_verify' vs 'unsupported'. It explicitly instructs that 'could_not_verify' must not be treated as evidence, which is valuable beyond 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?

The description is dense but every sentence contributes: trigger phrases, verification paths, verdict list, error semantics, and efficiency note. It is front-loaded with usage signals and avoids redundancy. Though long, it is appropriately sized for the tool's complexity and contains 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?

With no output schema, the description fully covers return values (verdict, actual value, citation, reasoning) and error behavior. It also covers parameter semantics, usage scenarios, and distinguishes from siblings. This is a complete standalone description that leaves no major operational questions unanswered.

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

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

Schema covers 100% of parameters, but the description enriches them meaningfully: 'tolerance_pct' is explained as overriding the claim's implied tolerance, with a specific use case (1–2 for hallucination detection) and a default cap. The 'claim' parameter is illustrated with concrete examples, adding practical guidance beyond the schema's field description.

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

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

The description opens with explicit trigger phrases and states a specific function: natural-language claim verification against authoritative sources. It clearly distinguishes the tool from siblings by detailing the two verification paths (SEC EDGAR XBRL fast path for company financials, grounded pipeline for all other claims) and mentions it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives trigger phrases. It also clarifies the scope (company-financial vs any other claim) but does not explicitly name when-not-to-use alternatives like ask_pipeworx or deep_research, so it lacks direct exclusion/sibling comparison.

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