Bps Id

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds return format (per-model score, confidence, signals, raw_response + combined view) and cost implication for Anthropic calls. No contradictions.

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

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

Four sentences covering purpose, details, return format, and use cases. No filler, front-loaded with main verb 'Probe'. Every sentence earns its place.

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

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

For a tool with 4 params, no output schema, no nested objects, the description fully explains input parameters, return structure, and use cases. No gaps.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining default model, how to probe Anthropic with _apiKey, and that context helps disambiguate. Goes beyond schema descriptions.

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

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

Clearly states it probes LLMs for entity knowledge and scores visibility (0-100) per model. Distinguishes from siblings like 'scan_competitor_ai_presence' and 'entity_profile' by focusing on AI visibility scoring and mentioning use cases.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to provide _apiKey for Anthropic. Lacks explicit exclusions or alternatives but provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context by noting that it returns structured answers with stable pipeworx:// citation URIs and that it is a fast single call, which goes beyond the annotations. It does not contradict any annotations and provides useful behavioral nuance.

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 critical 'PREFER OVER WEB SEARCH' statement, then lists applicable domains, explains routing behavior, provides concrete examples, and contrasts with siblings. Every sentence adds value, and it is well-structured despite its length, with a clear hierarchy of information.

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

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

For a complex tool that routes across thousands of sources, the description covers the core purpose, usage scenarios, alternative tools, and behavior (citation URIs, fast call). It includes multiple illustrative examples and clearly states the default-entry-point role. Without an output schema, it adequately conveys what the agent can expect in return.

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% description coverage for all six parameters, all being aliases for 'question'. The description itself does not elaborate on parameters, but the schema already documents them clearly with descriptions and examples. Since coverage is high, the baseline of 3 applies; the description adds no extra semantics 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 states a clear purpose: it routes questions to one of 5,621 tools across 1,472 verified sources, fills arguments, and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research, making the intent unambiguous.

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

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

The description provides explicit when-to-use guidance: it is the default entry point and should be preferred over web search for factual questions, even if web search could answer them. It also clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions), leaving no ambiguity about selection criteria.

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

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

Annotations already cover read-only, open-world, idempotent, and safe behavior. The description adds valuable context beyond annotations: candidate routing is enabled live when under test, the current state exactly matches ask_pipeworx, results are compared against the stable router for merges, and it is not a stub. This adds appropriate transparency 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 information is front-loaded and organized sensibly, but the description repeats 'same ... same ... same ...' and 'exactly like ask_pipeworx', includes a niche date that will become stale, and ends with the mildly confusing phrase 'Falls back to nothing'. Several sentences could be tightened.

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 beta variant of a known sibling tool, the description is adequate: it addresses current behavior, usage intent, and status as a full router. However, it provides no explanation of the actual response shape or routing output beyond 'same response shape', and it depends on knowing ask_pipeworx to be fully actionable.

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 question parameter and aliases at 100% coverage, so a 3 baseline is appropriate. The description merely repeats 'same arguments' and adds no additional semantic meaning or call-format guidance.

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 explicitly identifies the tool as a beta version of ask_pipeworx, states it is an identical universal router with the same tools, arguments, and response shape, and names it as the experimental routing edge. It distinguishes from the stable ask_pipeworx, but it still relies on sibling knowledge for what ask_pipeworx fundamentally does.

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

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

It gives explicit usage guidance: use it exactly like ask_pipeworx when you want the newest routing, and it can be relied on as a full working router even when no candidate is active. It does not explicitly exclude stable-production use or mention ask_pipeworx_grounded, but the stable-versus-experimental framing provides adequate context.

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

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

The description discloses key behavioral traits beyond annotations: it returns structured output with refusal reasons, uses exactly the tool result, and costs one extra LLM call. These details are not present in the annotations, and they do not contradict them. It also explains the refusal pathways, making behavior predictable.

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

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

The description is efficiently structured: it opens with the core value proposition, explains the mechanism, lists the return format, and gives concrete usage scenarios with a cost caveat. Every sentence contributes, and the language is precise and front-loaded.

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

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

For a tool with multiple siblings, an output schema (though none provided here), and straightforward input (a single question), the description provides everything an agent needs: usage guidance, behavioral expectations, output structure, and cost implication. No critical information 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 schema is fully documented with a single logical parameter 'question' that has multiple aliases, and the description does not add meaning beyond that. Since schema coverage is 100%, a baseline of 3 is appropriate; the description gives no extra parameter-specific nuance, but none is needed.

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

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

The description states a specific, well-defined purpose: it is a hallucination-resistant answer mode that routes like ask_pipeworx but only uses tool result content to produce answers with evidence. It clearly distinguishes itself from ask_pipeworx by adding the extraction step and the guarantee of not inventing facts, which separates it from sibling 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 this tool (for quotes, citations, or actions where facts must not be invented) and when not to (prefer ask_pipeworx for casual lookups). It also mentions the cost trade-off, giving clear criteria for selecting between alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details beyond annotations: status codes (low_confidence_match, market_closed_or_inactive), spread checks (illiquid_wide_spread), resolution-rule cancellation parsing, news field fallbacks, and response shapes. No contradiction.

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

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

Long but efficient, front-loaded with main purpose and input types. Uses visual structure (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for readability. Every sentence adds unique value; no redundancy.

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

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

Given no output schema, description fully covers return values, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and resolution contract. Provides comprehensive guidance for both common and exceptional scenarios.

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 3 parameters. Description adds value beyond schema: clarifies 'market' can be slug, URL, or question text; explains 'depth' enum (quick/thorough, default thorough); explains 'include_raw' boolean (default false, use case for true). This is more than the schema provides, so above 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?

Clearly states it researches Polymarket bets by pulling Pipeworx data, describes input types (slug, URL, question text), and explains what it does (resolve, classify, fan out, return evidence packet + market-vs-model comparison). Distinguishes from siblings implicitly by focusing on multi-source research, while siblings like polymarket_arbitrage or polymarket_edges are more specialized.

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 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which provides clear context. Does not explicitly exclude scenarios or mention alternatives, but the usage guidance is strong enough for correct invocation.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context on data sources (SEC EDGAR/XBRL, FAERS, etc.), fiscal year handling, and that results include 'pipeworx:// citation URIs.' No contradictions. A minor gap is the lack of mention about rate limits or data freshness, but overall useful.

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

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

The description is a single paragraph of about six sentences. It front-loads with example user queries, then states the core action, elaborates on each type, mentions result ordering, and concludes with efficiency benefits. Every sentence serves a clear purpose with no redundancy.

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

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

For a tool with 2 parameters and no output schema, the description thoroughly explains the return: paired data with citation URIs and sorted by primary metric. It covers financial metrics for companies and adverse-event/trial data for drugs, and even addresses fiscal year handling. It sets expectations by noting it replaces 8–15 sequential lookups. This is complete for its complexity.

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

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

The input schema has 100% description coverage for both parameters. The description enriches this by explaining the meaning of each type value (e.g., company pulls specific financial metrics, drug pulls adverse-event counts) and providing concrete examples for the values array (tickers for companies, drug names). This adds significant value beyond the schema.

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

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

The description begins with natural language queries and explicitly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It details the data pulled for each entity type (e.g., latest 10-K financials for companies, FAERS and FDA data for drugs) and notes results are sorted by primary metric. This clearly distinguishes it from sibling tools like entity_profile, which handles single entities.

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

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

The description includes an imperative: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong usage guidance. It also specifies the number of entities (2–5) and gives examples for both types. However, it does not explicitly state when not to use the tool (e.g., for single entity lookups), though that is implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description goes well beyond these by detailing the parallel decomposition across 5,621 tools, the exact structure of the findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), the hop mechanism, citation_uri resolvability, excerpting behavior for large records, and expected latency (15-90s). It also mentions account requirements. This richly supplements the annotation-level safety profile without contradiction.

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

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

The description is long but every sentence contributes new information—account requirements, core purpose, decomposition, output structure, exclusions, depth behavior, citation guarantees, excerpting, latency. It is front-loaded with the most critical constraint (account/sign-in). While a more structured format could improve scannability, it is appropriately sized given the tool's complexity and avoids fluff.

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

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

This is a highly complex tool (parallel routing across thousands of sub-tools) with no output schema, so the description must carry the full burden of explaining return values and edge cases. It explains the findings packet structure, gaps[] for unanswered facets, contradictions[], hop field, citation_uri conditions, excerpting of large records, and latency variance. It also covers account tiers and when to use alternatives. Nothing an agent needs to call it effectively 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?

Although schema coverage is 100% (both parameters have descriptions), the tool description adds substantial meaning. It clarifies that 'question' can be broad/multi-part and that decomposition is automatic, something the schema only implies. For 'depth', it explains the behavioral consequences of each enum value (number of facets, hop counts, gap-recovery, contradictions scan), which goes far beyond the schema's one-liner. This is clearly value-additive over 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 starts with a clear verb 'research' and specifies the resource: 'Pipeworx's 1472 STRUCTURED data sources'. It explicitly distinguishes itself from open-web search ('this is NOT open-web search') and differentiates from siblings by naming ask_pipeworx as the alternative for single lookups and current news. This leaves no ambiguity about what the tool does and how it differs from nearby 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 ('Best for broad/multi-part questions over structured data') and clear when-not-to suggestions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also names the alternative tools directly and explains the condition that routes to them, leaving no inference needed.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds beyond this: '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 explains the return format and actionable results, which is critical behavioral context not in 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 moderately long but efficiently structured: purpose first, then usage guidance with domain examples, then return details. Every sentence serves a purpose, though the list of domains could be slightly trimmed without loss. Still, it's well-organized and front-loaded.

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

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

Given no output schema, the description fully explains what the tool returns (top-N tools with schemas and examples) and how to use the results (ready to call directly). It also covers the tool's role in the ecosystem ('Call this FIRST'). For a discovery tool with simple query input, this is completely sufficient.

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

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

Schema description coverage is 100% with detailed property descriptions. The description's mention of 'query' and its aliases adds no new semantic value beyond what the schema already provides. Baseline score of 3 is appropriate as the description doesn't enrich parameter meaning.

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

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

The description clearly states 'Find tools by describing the data or task', using a specific verb and resource. It distinguishes itself from siblings by explicitly noting 'Call this FIRST when you have many tools available and want to see the option set', setting clear boundaries vs other 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 provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a detailed list of domains. It also gives a clear directive to call this tool first to see options, implying when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond these: it explains the multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), details the return structure (cik, filings up to 5 with URIs, fundamentals sorted, patents soft-fail, news fallback), and notes USPTO API sunset. No contradiction found.

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

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

The description is a single dense paragraph, but it is front-loaded with examples and every sentence adds value. It could be slightly more structured (e.g., bullet points for return fields), but it remains concise and effective for its length.

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

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

The tool has 2 required params and no output schema. The description compensates by fully explaining the return payload: sources (SEC, XBRL, USPTO, news, GLEIF), specific fields (cik, filing URIs, fundamentals sorted, patents status, news fallback, LEI), and limitations (USPTO sunset, name not supported). This provides complete contextual understanding.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value beyond schema: it confirms 'type' only supports 'company', specifies that 'value' must be a ticker or zero-padded CIK, explicitly says names are not supported, and provides examples like 'AAPL' and '0000320193'. This enriches the schema info.

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 colloquial examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings by specifying it should be preferred over chaining individual lookups and notes that names are not supported, directing to resolve_entity.

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 when to use (when user asks for a holistic view of a US public company) and when not to (if only have a name, use resolve_entity first). It also gives explicit preference over chaining single-pack lookups, providing clear 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 destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data, but does not 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?

Two short sentences, front-loaded with the action, no wasted words.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description is complete: purpose, usage, and pairing guidance are all present.

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 schema already describes the 'key' parameter as 'Memory key to delete'. The description does not add additional meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with remember and recall, but does not explicitly say when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it fetches the page and extracts title/description/key links, providing operational detail without contradicting annotations.

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

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

Two sentences plus a bullet-point list of use cases. Every sentence adds value; no wasted words. Front-loaded with the core 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?

Given the tool's simplicity, the description fully explains input, process, and output ('single text blob ready to drop at site-root/llms.txt'). No output schema needed.

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 are well-described in the schema. The description does not add additional meaning beyond what the schema provides, so 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 it generates a production-ready llms.txt for any URL, specifying the output format and use cases. It distinguishes itself from siblings by focusing solely on llms.txt generation.

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

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

The description lists three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not explicitly mention when not to use or 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 declare readOnlyHint, idempotentHint, etc. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which are not in the annotations. 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?

Two concise sentences with no wasted words. The first sentence states the primary purpose immediately. Every sentence earns its place.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers the main aspects: what it returns, when to use it. It could mention potential limits or pagination, but it's not critical for this tool. The annotations cover safety.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The description adds context by explaining why you'd use the tool (review before adding, find id to cancel), which indirectly clarifies the parameter's purpose. This goes 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 'List the caller's active subscriptions' with a specific verb and resource. It specifies the scope (active) and optional inclusion of inactive. However, it does not explicitly differentiate from sibling tools like subscribe/unsubscribe, but the use case hints help.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool (reconnaissance, cancellation). No alternative siblings are named, but the context is sufficient.

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

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

Annotations are all false, so no safety profile is provided there. The description fills this gap by disclosing key behaviors: filing without an account returns a claim_token, which can be passed back later to read status; it is rate-limited to 5 per identifier per day; it's free and doesn't count against tool-call quota; the team reads digests daily. This far exceeds what annotations offer and gives the agent a clear understanding of side effects and limitations.

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 the description is relatively long, every sentence earns its place. It front-loads the purpose, then efficiently covers usage triggers, exclusions, formatting guidance, the claim_token mechanism, rate limits, and quota impact. There is no redundant fluff or restatement of the tool name; each clause adds a distinct piece of actionable 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 tool's moderate complexity (four params, one nested object, two operating modes), the description is exceptionally complete. It explains both the 'file feedback' mode and the 'claim_token lookup' mode, clarifies scope (only Pipeworx tools from this connection), and mentions rate limits and daily reading. Since there is no output schema, the description adequately describes what filing returns and how to later retrieve resolution status.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful param semantics beyond the schema: it explains the claim_token workflow with a concrete usage example (pipeworx_feedback({claim_token:"pwfb_…"})), clarifies that message should be 1-2 sentences typical, and gives real-world context for the type enum (e.g., data_gap is data Pipeworx does not currently expose). This enriches, though the schema itself is already well-described.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exactly what kinds of feedback are accepted (bug, feature/data_gap, praise), making the tool's purpose unmistakable. It also implicitly distinguishes from sibling research/visibility tools by focusing on reporting issues about Pipeworx itself rather than querying 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 explicit when-to-use scenarios ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)'). It also gives a clear exclusion: if the tool comes from a different MCP server, file it there instead. Guidance on what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') further helps the agent decide and use correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradiction.

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

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

Three concise sentences plus bulleted use cases. Front-loaded with core purpose. No fluff; every sentence 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?

Covers input, output content, data source, privacy, caching. Lacks exact output format but acceptable for a simple trending tool without output schema.

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

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

Schema covers parameter fully (100% coverage). Description adds extra context about window behavior (shorter for hot, longer for steady-state) beyond schema 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?

Description clearly states the tool returns trending usage data: top tools, packs, and call volume. Distinguishes from sibling 'discover_tools' by focusing on real-time popularity rather than general 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?

Explicitly lists three use cases (hot data, canonical choice confirmation, alignment check). Does not explicitly state when not to use, but the use cases are clear and context-rich.

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, but the description adds rich behavioral context: internal algorithms (Jaccard similarity threshold of 0.30, placeholder filter with >20% threshold), fill check against CLOB depth with 'realizable_edge_pp ≤ 0 means do not trade', and detailed response structure. 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: general purpose, parameter explanations, then additional details (semantic anchor, partition filter, fill check). Every sentence adds value, though a few sections (e.g., fill check) could be slightly more compact. Overall, it is appropriately sized for the tool's complexity.

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

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

Given the tool has 2 optional parameters, no output schema, but high complexity, the description is complete. It describes the response fields (opportunities array, partition_check, fill_check), provides thresholds (3pp, 20%), and even refers to a sibling tool (polymarket_fill_risk) for custom sizing. No gaps identified.

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%, baseline 3. The description adds significant value: explains event parameter as single-event mode with slug/URL examples, topic as cross-event scanning with seed question examples, and details what happens internally for each. This far exceeds schema documentation.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by focusing on arbitrage detection rather than edge tracking or fill risk.

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

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

Explicit guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It provides concrete examples of slugs and seed questions. It explains when each mode is appropriate and what cross-event mode catches that single-event misses, though it does not explicitly state when not to use the tool.

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

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

Annotations are readOnly, openWorld, idempotent, and non-destructive; description adds substantial context: model families, Kelly sizing, slippage treatment, tradeable-edge knobs, caching at KV level keyed on knobs, and diagnostics for empty segments. No contradictions.

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

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

Very long (~500 words) with detailed model formulas and mechanics. Front-loaded with purpose, but includes excessive detail for initial comprehension. Could be more concise while preserving critical info.

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

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

Despite no output schema, description fully explains response structure (by_segment, diagnostics, fed_candidates), caching behavior, and edge calculations. Covers all parameters and their interplay, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, but description adds value: explains min_kelly skips small opportunities, gives examples for max_spread_pp and min_liquidity, clarifies min_partition_leg_kelly filters per-leg Kelly inside partitions. Adds rationale for defaults and usage hints.

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

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

Description states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, built for 'what should I bet on today'. It clearly distinguishes from siblings like polymarket_arbitrage or polymarket_edge_tracker by its focus on cross-data discrepancies and comprehensive edge metrics.

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 targets agents discovering opportunities without paging hundreds of markets. Includes exclusion: Fed bets are surfaced but excluded from ranking due to unreliable signals. While alternatives are not named, the purpose is clear enough to guide usage.

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

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

Annotations already declare the tool read-only and idempotent. The description adds substantial behavioral context: response structure (tracked, expired, snapshot_dates), meaning of trend and decay fields, and limitations like snapshot TTL and gap handling. 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 front-loaded with the key question, then systematically explains response sections and limitations. It is comprehensive but slightly verbose; a minor trim could improve conciseness.

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

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

Given no output schema, the description fully explains return values and limitations. It covers tracked/expired fields and snapshot gaps. Minor gap: does not discuss error cases or data freshness beyond snapshot dates.

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 parameters well-documented. The description adds slight nuance (defaults, clamps) but largely repeats schema information. Baseline 3 is appropriate as the schema carries the burden.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?' It distinguishes from the sibling 'polymarket_edges' by focusing on historical trends rather than current values.

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 (to assess edge persistence and decay) and implies scenarios where a fresh edge differs from a stale one. However, it does not explicitly state when not to use it or name alternatives like '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 already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds behavioral details: walks the ladder, returns verdicts (clean|degraded|cannot_fill), and highlights risk of unhedged directional position. No contradictions with annotations.

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

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

Description is well-structured with single-market and basket sections, bolded keywords, and clear flow. However, it is verbose with some redundancy (e.g., 'SINGLE-MARKET:' and 'BASKET:' could be tighter). Still earns its length due to 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?

No output schema, yet description fully enumerates all return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. Comprehensive 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%, but description adds significant meaning: explains how side defaults vary by mode, how size_usd is interpreted differently (max spend for buys vs target proceeds for sells in single-market, settlement notional in basket), and provides clamp range. Enriches schema beyond basic 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?

Description explicitly states tool does realizable-vs-theoretical edge check against live CLOB order-book depth. Clearly distinguishes single-market and basket modes with specific return fields. Sibling tools like polymarket_arbitrage and polymarket_edges are referenced, establishing unique purpose.

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

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

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'. Explains requirements (one of market or event) and gives rationale for usage (theoretical overround not capturable, partial fills cause unhedged positions).

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

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

Annotations indicate safe, idempotent, read-only operation. Description adds detailed behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases when spreads are invalid. No contradictions.

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

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

Description is relatively long with detailed explanations of safety fields and counters. While well-structured with labeled sections, some details (e.g., skipped_cross_type/subtype counters) could be more concise or placed in the output schema if available.

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?

No output schema; description compensates by fully explaining return values (leg-by-leg prices, spread[], top_spreads_pp) and safety fields. Covers all edge cases and parameter use cases. Highly complete for a moderately 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 100%; description adds meaning beyond schema: lists all 10 topic shortcuts, provides explicit ticker examples, explains override behavior. Each parameter's role in the two modes is clearly articulated.

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 verb (computes spread) and resource (cross-venue between Kalshi and Polymarket). Distinguishes from siblings like polymarket_arbitrage by focusing on same resolving question comparison.

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

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

Explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, guiding when to use and that tradeable spreads are rare. However, no direct comparison to alternative tools for similar tasks.

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, destructiveHint. Description adds scope (scoped to identifier) and behavior when key is omitted. No contradictions.

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

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

Three sentences cover purpose, usage, and scope without any unnecessary words. Front-loaded with the core 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully explains main functionality, pairing with siblings, and scope.

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

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

Schema has 100% coverage with one optional 'key' parameter. Description adds that omitting key lists all keys, and explains the purpose of the key within the tool's workflow.

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

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

Clearly states the tool retrieves a value saved via 'remember' or lists all keys when omitted. Distinguishes from siblings 'remember' and 'forget', and provides concrete use cases like user target ticker or address.

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 when to use (look up stored context) and pairs with remember/forget. Implicitly distinguishes from re-deriving information, but does not mention explicit when-not 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?

The description contradicts the readOnlyHint annotation: it states 'Set mark_read:true to flag returned events read', which implies a write operation, while annotations mark the tool as read-only. This inconsistency undermines transparency and could mislead the agent.

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

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

The description is front-loaded with the core purpose and logically progresses to details. It includes a helpful alternative access method. While slightly lengthy, every sentence adds value; one could argue removing the last sentence for brevity.

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 return structure (source, citation_uri, payload) and covers all parameters with usage context. It addresses polling suitability. Missing error handling or rate limits, but acceptable for a read tool.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds behavioral nuance beyond the schema (e.g., explaining mark_read's effect and default 50 limit), earning a 4. However, it does not describe the 'unread_only' parameter explicitly.

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

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

The description clearly identifies the tool as 'Pull fired events from your subscription feed' and specifies the return fields (source, citation_uri, payload). It distinguishes this retrieval tool from subscription management siblings like 'subscribe' and 'unsubscribe' by focusing on event history.

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 good usage context: filtering by type and since, setting mark_read, and noting that polls work fine. It even offers an alternative access method for scripts/dashboards. However, it does not explicitly compare to similar retrieval tools (e.g., 'recent_changes') or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: fanning out to multiple sources, fallback logic, return structure (changes grouped by source, total_changes count, citation URIs), and the USPTO soft-fail pending PatentsView API reactivation. No contradictions.

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

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

The description is a single paragraph but packs significant detail efficiently. It front-loads example queries and then elaborates on sources and behavior. Every sentence adds value, though slightly denser than necessary for trivial understanding. Still very good conciseness.

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

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

Given the tool's moderate complexity (multi-source, fallback, no output schema), the description covers the core behavior comprehensively: what it does, how it works, expected return structure, and limitations (USPTO soft-fail). It leaves no major gaps for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter types (ticker vs CIK), giving concrete examples for 'since' ('7d', '30d', '3m', '1y'), and recommending '30d' or '1m' for typical monitoring. This enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a date range, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It uses specific verbs and distinguishes itself from sibling tool entity_profile, making the purpose unmistakable.

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

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

The description includes example queries ('What's new with X', 'latest on Y') and explicitly contrasts with entity_profile for static profiles. It also explains when GDELT is preferred over GNews and notes the USPTO soft-fail, giving clear guidance on usage context and 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?

Adds behavioral context beyond annotations: scoping by identifier, persistence differences between authenticated and anonymous sessions. No contradiction with annotations (idempotentHint true aligns with storing).

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-sentence paragraph is front-loaded with purpose, no wasted words. Every sentence adds valuable 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 tool's simplicity (2 params, no output schema), the description covers purpose, usage, behavioral traits, and pairing with siblings. Fully sufficient for correct tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description does not repeat schema details but provides usage examples that imply parameter semantics. Adds moderate value beyond schema.

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

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

The description clearly states the tool saves data for later reuse, specifying the action (save), resource (key-value pair), and context (across sessions). It distinguishes from sibling tools like recall and forget.

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

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

Provides explicit when-to-use guidance with examples (resolved ticker, user preference) and pairs with recall/forget. Lacks explicit when-not-to-use but context is clear enough.

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

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

Annotations state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond those: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` field for identifiers that cannot be resolved, source labelling, and internal cascading lookups. 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 relatively long, but it is well-structured with section labels and front-loaded examples. Every sentence adds meaningful detail for a complex tool. However, the opening list of example phrasings could be trimmed; it is slightly verbose, making it less crisp than ideal.

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 two entity types, multiple identifier sources, no output schema, and cascading lookups. The description fully covers return values (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand, citation), edge cases (unresolved, ISIN mapping, non-US issuers), and failure behavior (graceful degradation). This is comprehensive enough for an agent to use it correctly without an output schema.

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

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

Schema covers both parameters with descriptions, but the description enriches semantics substantially: it explains the full meaning of `type` (company vs drug), acceptable `value` formats for company (ticker, CIK, ISIN, name) and drug (brand/generic), and special cases like ISIN resolving to legal entity. This goes far beyond the schema's one-line 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 explicitly states the tool resolves a user-spoken NAME to canonical/official identifiers, with a clear verb (`resolve`) and resource (`entity`). It distinguishes itself by emphasizing it provides IDs needed by other tools, and provides numerous example queries that frame the intent. This clearly differentiates it from siblings like `entity_profile` or `compare_entities` which likely consume IDs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', a direct when-to-use instruction. It also explains supported types and input formats, and notes that it replaces 2-3 manual lookups, signaling when it is the appropriate shortcut. This is precise actionable guidance.

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

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

The description discloses that it probes each entity with ai_visibility_check, which adds behavioral context beyond the annotations (which already indicate read-only and idempotent). It also describes the return structure (ranked list with scores). 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 two sentences plus a brief use-case sentence. It is front-loaded with the main purpose and efficiently provides additional detail without unnecessary words.

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

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

The description covers purpose, internal mechanism (calling ai_visibility_check), and output format (ranked list with score, confidence, signal density). No output schema exists, so the description compensates well. It could mention parallelism, but the schema already specifies entity count constraints.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by stating that the first entity is treated as the subject and the rest as competitors, which is not in the schema. This extra semantic clarifies the expected order and narrative emphasis.

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

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

The description clearly states the verb 'compare' and the resource 'AI visibility across multiple entities'. It distinguishes from sibling tools by referencing the internal call to ai_visibility_check and the side-by-side comparison, which is not provided by single-entity tools. The use case and output format are explicitly mentioned.

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

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

The description provides clear context for when to use this tool: for competitive AI-marketing audits. It hints at alternatives by mentioning `ai_visibility_check` as the underlying probe, implying single-entity use. However, it does not explicitly list when not to use or other alternatives, which prevents a score of 5.

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

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

Beyond annotations (readOnlyHint, etc.), description adds partial failure handling, timing details (5-30s for bundlephobia first measurement), and sources_failed behavior.

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

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

Description is relatively long but well-structured. Front-loaded with the composite nature and covers all key points without 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?

Given the tool's complexity (composite of two services) and lack of output schema, description thoroughly explains return format, behavior, and edge cases. 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%, so baseline is 3. Description adds extra context for both parameters: scoped packages accepted for 'package', default to latest for 'version'. 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?

Description clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes itself from alternative tools for other ecosystems.

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

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

Explicitly says when to use: when agent asks about safety, popularity, size, or cost. Also specifies NPM ecosystem only, directing other ecosystems to deps.dev:version.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and a 200K character cap (with truncation flag). 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 concise yet complete. Every sentence serves a purpose: core function, usage context, pairing advice, and technical details. It is front-loaded with the primary action and avoids superfluous 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 tool's complexity (3 parameters, no output schema), the description covers all necessary aspects: input, process, output (passages with offsets and scores), limits, and truncation behavior. The agent has enough context to use the tool effectively.

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

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

Schema coverage is 100% with good descriptions. The description enhances parameter semantics by providing concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue') and reinforcing the text limit. This adds practical value beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb-resource pair ('search within source'). It distinguishes itself from siblings by mentioning when to use (record too big for prompt) and pairing with ask_pipeworx_grounded.

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

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

The description explicitly states when to use this tool: when the record is too big for the prompt. It also explains the benefit (saves context) and pairs with a sibling. However, it does not explicitly list when not to use or provide comprehensive alternatives beyond mention of ask_pipeworx_grounded.

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 behaviors beyond annotations: requires OAuth account, returns subscription id, delivery channels (feed always on, optional email/sms/webhook with constraints like SMS cap and webhook auto-disable after 10 failures). 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 informative but relatively lengthy. It is front-loaded with the core purpose, then requirements, then types, then delivery. Every sentence adds value, but could be slightly more structured (e.g., bullet points) for quick scanning.

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 has 3 parameters (including nested objects) and no output schema, the description covers return value (subscription id), supported types with detailed examples, and delivery channel specifics. It lacks explicit error handling or limits beyond SMS cap, but 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?

Schema coverage is 100%, so baseline 3. The description adds significant value by explaining each type with example parameters and delivery channel details (e.g., webhook signing, SMS verification requirement). This elevates understanding beyond the schema.

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

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

The description clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value 'Returns the new subscription id'. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by detailing the subscription creation process.

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 this tool (monitoring live data events) and prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist). It lists supported types with examples but does not explicitly exclude situations or mention alternatives beyond sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral context: returns example questions with tool+argument shapes from the live catalog, and that it's the first tool to call. 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 somewhat lengthy but every sentence provides useful information. It is front-loaded with example triggers, then explains output and usage. Could be slightly tighter, but no wasted words.

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

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

For a tool with one optional parameter and no output schema, the description is fully complete. It covers purpose, usage, output structure, when to use, and how to parameterize. No gaps.

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

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

Schema coverage is 100% (only 'topic' is documented). Description enhances by listing example values ('finance', 'pharma', etc.) and explaining that omitting gives a cross-category spread. This adds meaningful usage context beyond the schema 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 clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It lists common user queries ('what can I ask Pipeworx?') and explains the output format, distinguishing it from sibling tools by specifying it should be used first when unsure about Pipeworx's capabilities.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions how to learn meta-tools. Also explains optional topic parameter for focusing, providing clear when-to-use guidance.

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

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

The description adds significant value beyond annotations: it explains that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. Annotations only indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description provides crucial behavioral detail.

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

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

The description is highly concise (two sentences) and front-loaded with the action. Every sentence adds value: ownership enforcement and behavioral effect. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It explains ownership, the fact that the row is deactivated rather than deleted, and the impact on historical events via recent_alerts. Nothing essential is missing.

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

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

Schema coverage is 100% and the parameter 'id' is already described well in the schema as 'Subscription id (uuid) returned by subscribe'. The description mentions 'by id' but does not add substantial new meaning beyond the schema.

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

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

The description clearly states 'Cancel a subscription by id.', specifying the action (cancel) and the resource (subscription). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by describing the effect (deactivation) and ownership enforcement.

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

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

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear context on when to use. While it doesn't explicitly mention alternatives, the sibling tools list provides context, and the description is sufficient for usage guidance.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses critical behavioral semantics: could_not_verify means the check did not happen and carries a verification_error, while unsupported means no source was found. It also reveals the internal routing between the structured SEC/XBRL fast path and the grounded pipeline, adding context that annotations cannot convey.

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

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

The description is long but densely informative, front-loading usage examples and then logically progressing through the two execution paths, return types, and caveats. Every sentence contributes unique information, and the structure supports quick scanning for trigger phrases.

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

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

For a tool with no output schema, the description thoroughly explains return values (verdict list, actual value with pipeworx:// citation, reasoning) and the distinction between failure modes. It also covers the two input parameters, internal routing, and practical efficiency benefit, making it fully self-contained for an AI agent.

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

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

Both parameters are already documented in the schema (100% coverage), but the description adds essential behavior for tolerance_pct — it overrides the tolerance implied by the claim wording, allows 1–2% for hallucination detection, and defaults to a cap of 5. This gives agents the exact context needed to choose a value for the desired strictness.

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

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

The description clearly states this tool performs natural-language claim verification against authoritative sources, with concrete example queries and a defined verdict set. It distinguishes itself from sibling research/query tools by focusing on fact-checking with a structured verdict, and it details the two execution paths (SEC EDGAR for company-financial claims, grounded pipeline for other claims).

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

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

The description explicitly says to use it whenever the agent needs to check whether something the user said is factually correct, and it explains how company-financial claims vs other claims are routed internally. It also notes that it replaces 4–6 sequential calls, positioning it against a manual multi-step alternative, though it does not name specific sibling tools for non-fact-checking queries.

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