Scream Void

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds useful context: cost/API key implications, default vs paid models, and output format (per-model score, confidence, signals, raw_response). It does not cover error handling or rate limits, but the extra detail is valuable.

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

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

The description is a single paragraph of 4 sentences, efficiently covering key points without fluff. It is front-loaded with the main action, though could benefit from slight restructuring (e.g., bullet points) for even faster 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?

The description explains the return format and use cases but lacks details on failure modes (e.g., unknown entity, model errors) or limitations (e.g., model list). With 1 required param and no output schema, more guidance on edge cases would improve completeness.

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 context about the default model and API key usage but does not provide new details per parameter beyond what the schema already offers. Example: it mentions context helps disambiguate, aligning with 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 probes LLMs for entity knowledge and scores visibility (0-100). It uses a specific verb ('probe') and resource ('LLMs for visibility'), effectively distinguishing it from sibling tools like ask_pipeworx (single-model Q&A) or deep_research (broader research).

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly compare to alternatives like scan_competitor_ai_presence or when not to use. The agent may need more guidance to select among similar siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it routes to tools, fills arguments, and returns stable citation URIs, which goes beyond the annotations. It does not contradict annotations. A slight deduction because the description doesn't detail the exact return format or error behavior, but it adds enough context.

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

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

The description is long but well-structured and front-loaded with the key instruction ('PREFER OVER WEB SEARCH'). It uses clear sections: scope, usage guidance, examples, and alternatives. Every sentence serves a purpose, and the length is justified for a default entry point. Minor redundancy (e.g., 'START HERE' repeated) but overall efficient.

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

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

For a tool that routes to thousands of sources, the description is exceptionally complete. It explains the routing behavior, citation URIs, when to use, when not to, examples, and alternatives. Despite no output schema, it conveys what the user gets (structured answer with URIs). Nothing critical 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% with a clear description for each alias parameter. The description itself adds no extra parameter-specific meaning beyond what the schema provides—it only reinforces the 'natural language' nature. Baseline 3 is appropriate when the schema already documents parameters.

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 routes questions to 5,801 tools across verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and specifying its scope ('current or historical data'). The verb+resource is specific and 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?

Explicitly says 'PREFER OVER WEB SEARCH' and gives conditions for use ('any factual question about real-world entities, events, or numbers'), with examples. It clearly states when to step up to alternatives (grounded for hallucination-resistant single answer, deep_research for broad/multi-part). Even covers breaking news routing. Nothing is left to inference.

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 is transparent about the experimental nature: it is a beta version, may have candidate routing improvements, currently matches ask_pipeworx exactly, and 'falls back to nothing' but is a full working router. This aligns with the annotations (readOnlyHint, idempotentHint, destructiveHint false) and does not contradict them.

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

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

The description is somewhat redundant and rambling, repeating 'identical', 'same', and 'exactly' multiple times. It could be condensed into a clearer structure, though the information is relevant and not excessively long.

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 provides necessary context about its beta status, relationship to the stable version, current behavior, and fallback. While it does not detail return values or the meaning of 'routing,' the context is sufficient for an agent to understand how to use it, especially given the absence of an output schema.

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

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

Schema description coverage is 100%, and the schema already explains that 'question' accepts aliases including q, prompt, text, input, and query. The tool description adds no further parameter meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and states it is identical in function, arguments, and response shape. It does not explicitly define what 'universal router' does, but the reference to ask_pipeworx and the context of sibling tools make the purpose reasonably clear.

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

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

The description provides explicit guidance on when to use this tool: 'when you want the newest routing.' It contrasts with the stable ask_pipeworx and notes that results are compared against the stable router, giving the agent a clear basis for selection among similar 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?

Discloses important runtime behavior beyond annotations: it performs an extra LLM call, returns verbatim evidence, refuses with specific reason codes when data does not directly answer, and never invents facts. This complements the readOnly/idempotent hints and sets accurate expectations.

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

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

The description is rich but slightly repetitive, explaining the routing and extraction flow twice ('picks the right tool... fetches the data' and 'then EXTRACTS'). Overall it is well-structured with clear use cases, but a bit longer than strictly necessary.

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

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

Despite lacking an output schema, the description fully specifies the return shape, including fields like evidence and confidence, and lists all possible refusal_reason values. This gives an agent complete context to interpret results correctly.

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

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

The schema already covers all six parameters with descriptions and alias relationships at 100% coverage. The description adds no additional semantic nuance beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, and explicitly contrasts with ask_pipeworx by emphasizing extraction only from tool results. The verb 'answer' and resource scope are unambiguous, and it distinguishes itself from the sibling ask_pipeworx.

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: whenever answers will be quoted, cited, or acted on, and when the agent must not invent facts. Also advises preferring ask_pipeworx for casual lookups, and enumerates refusal conditions, giving clear decision rules.

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 extensive behavioral traits beyond annotations: it explains the internal process (resolve market, classify, fan-out to data packs), details response shapes (market, analysis, evidence), outlines safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread flag), and even includes resolution-rule risk and parent event extraction. This goes far beyond the annotations (readOnlyHint, openWorldHint, etc.), providing agents with a complete mental model of the tool's execution.

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

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

The description is front-loaded with a clear purpose sentence, but then becomes quite lengthy with many details (classifiers list, fan-out examples, response shapes, resolver contract, parent extractor, news fields, safety, resolution-rule risk). While all information is valuable, it could be more compressed or structured as separate sections. Every sentence earns its place, but the verbosity reduces quick scannability for an AI agent.

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 (multiple classifiers, fan-out to diverse data sources, various response fields), the description is remarkably complete. It explains the output structure in detail (market, analysis, evidence), covers edge cases (low confidence, closed markets, wide spreads, resolution-rule risk), and provides concrete fan-out examples. Without an output schema, the description fully compensate by describing all possible response fields and behaviors.

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?

Input schema coverage is 100%, with each parameter already having a clear description (market: slug/URL/question text; depth: quick/thorough default; include_raw: summary vs full payload). The tool description adds no new parameter-specific information beyond what the schema provides; it mainly contextualizes overall behavior. Per guidelines, baseline score is 3 when schema coverage is high, which is appropriate here.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (bet), action (research), and outcome (data pull). The description further distinguishes from siblings by detailing use cases like 'should I bet on X' and showcasing wide scope (crypto, fed, sports, etc.), making it unique among tools like ask_pipeworx or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It provides examples of query types (slug, URL, question) and offers extensive post-invocation guidance on interpreting results (resolver contract, parent event, news fields, safety). However, it does not explicitly mention when NOT to use it or directly compare to sibling tools, leaving some implicit inference required.

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

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

The description adds extensive behavioral context beyond annotations: it details the data sources (EDGAR/XBRL for companies, FAERS for drugs), the specific financial metrics and counts retrieved, handling of off-calendar fiscal years, sorting by primary metric, and output format with citation URIs. No contradiction with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 clear and well-structured, starting with example queries and ending with output details. While it packs substantial information, it is slightly lengthy but remains effective 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?

Despite lacking an output schema, the description fully explains the returned data: paired data per entity, citation URIs, and sorting behavior. It covers both entity types comprehensively, making it self-sufficient for an agent to understand what the tool returns.

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

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

With 100% schema coverage, the description still adds significant value by explaining the semantics of each type ('company' vs 'drug') and giving concrete examples for values (tickers for companies, drug names). It also clarifies array constraints (min 2, max 5).

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

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

The description clearly defines the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verbs like 'compare' and 'rank' and distinguishes from sibling tools by explicitly stating preference over sequential single-pack lookups.

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 strong usage guidance, listing typical user queries ('X vs Y', 'which is bigger') and explicitly instructing to prefer this tool over sequential lookups. It does not explicitly state when not to use it, but the input schema's max of 5 entities 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 mark read-only, idempotent, open-world. The description adds rich behavioral detail: latency expectations, hop fields, contradiction scans, semantic excerpting, and guaranteed-fetchable citations. 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 information-dense, front-loading the key differentiator and then layering depth mechanics. Some redundancy (e.g., 1517 sources and 5,801 tools repeated) slightly bloats it, but the structure is logical and scannable.

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

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

No output schema exists, but the description fully compensates by explaining the return format (findings packet, citations, gaps[], contradictions[]) and behavioral expectations. Enough for an agent to decide and call 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 covers 100% of parameters; the description goes further by explaining depth values in detail (quick/standard/thorough mechanics) and reiterating question semantics. Adds meaning beyond the schema.

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

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

The description clearly states the tool's function: grounded multi-source research across structured data, with decomposition and parallel routing. It explicitly distinguishes itself from ask_pipeworx (structured vs. news), 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?

It gives explicit when-to-use (broad/multi-part structured-data questions) and when-not-to-use guidance (breaking news, single lookups, prefer ask_pipeworx), plus depth-level recommendations. No ambiguity about selection.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond these annotations, explaining that results include full input schemas and are ready to call directly, without needing a second lookup.

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

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

The description is concise with three sentences, front-loads the purpose, and includes essential information about return value and usage guidance without any filler.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains what is returned (top-N tools with names, descriptions, and full schemas) and lists example domains. It provides sufficient context for an agent 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 description coverage is 100%, so the schema already documents all parameters. The description does not add significant additional meaning to the parameters beyond what is in the schema. It mentions aliases but those are already listed in the schema. Thus a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find) and resource (tools), and distinguishes itself from sibling tools by being the only tool discovery tool available.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and 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 (readOnly, idempotent, openWorld, non-destructive), the description discloses cross-source fan-out, soft-failure for the USPTO PatentsView API, the meaning of empty sections as real "no data" rather than bugs, resolved:false behavior for private companies, and fallback chains like GDELT→GNews. This is exceptional transparency.

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

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

The description is front-loaded with examples and a crisp one-line purpose, and every sentence carries useful operational detail. However, it is a very long single-paragraph block; splitting it into sections would improve scannability, so it is not fully concise.

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

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

For a complex tool with no output schema, the description enumerates all returned sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed), explains edge cases, and documents failure semantics. Nothing essential is missing for correct invocation.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: zero-padded CIK format, interchangeability of "company" and "ticker", name resolution via SEC EDGAR, and examples for each input shape.

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 immediately identifies the tool as a full cross-source profile of a US public company via natural-language intents like "Tell me about X" and "brief me on Tesla". It names its explicit output sections and contrasts itself with chaining single-pack SEC/XBRL/news lookups, so an agent can clearly distinguish it from sibling research 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 an explicit usage directive: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also states the accepted input shapes, the private-company behavior, and that person/place coverage is not yet available, providing clear when-to-use and implied when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data but does not clarify idempotency (idempotentHint=true) or behavior for missing keys.

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: first defines the action, second provides usage guidance. No redundant words, information efficiently 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 simple tool with one parameter, description covers purpose, use cases, and related tools. No output schema but not critical; slight gap in return value description.

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

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

Schema covers the single parameter 'key' with description 'Memory key to delete'. Description adds no further detail beyond 'by key', so baseline 3 is appropriate.

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

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

Clearly states the verb 'Delete' and the resource 'previously stored memory by key', distinguishing it from siblings like remember (store) and recall (retrieve).

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 situations to use: when context is stale, task done, or clearing sensitive data. Suggests pairing with remember and recall, but does not explicitly state 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value beyond annotations, though it doesn't mention rate limits or page size considerations.

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: two sentences plus a bullet-like list of use cases. It is front-loaded with the primary action and purpose, and every sentence contributes meaning without redundancy.

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

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

Given the tool has 2 parameters, no output schema, and full annotations, the description covers input (URL, max_links), process (fetch, extract, format), output (standard llms.txt markdown), and use cases. It is fully adequate for an AI agent to understand and invoke the tool.

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

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

Schema description coverage is 100% and both parameters ('url' and 'max_links') are already well-described in the schema. The description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb ('generate'), resource ('llms.txt file'), and purpose ('so AI crawlers can index the site cleanly'). It distinguishes from siblings by focusing on AI crawler indexing and standard markdown format.

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 explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'), providing clear context for when to use. However, it does not explicitly state when not to use or compare to sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint and non-destructive. Description adds behavioral details: returns specific fields and mentions active vs inactive subscriptions. 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?

Two concise sentences with all essential information, no fluff.

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

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

Complete for a simple listing tool: covers purpose, return fields, usage context, and parameter. 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?

Single parameter 'include_inactive' is fully described in schema (100% coverage). Description does not add extra semantics 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?

Description clearly states 'List the caller's active subscriptions' – specific verb and resource. Distinguishes from siblings like subscribe and unsubscribe.

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 to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use the tool. No exclusions or alternatives mentioned, but sufficient for the simple tool.

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

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

The description goes far beyond the annotations (which only indicate non-read-only, non-idempotent, non-destructive). It discloses the claim_token mechanism ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), the rate limit ('Rate-limited to 5 per identifier per day'), and that it's free and doesn't count against tool-call quota. These are critical behavioral traits not captured in structured annotations.

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

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

The description is long but each sentence serves a purpose: clear purpose, usage criteria, exclusions, token flow, rate limits, and daily digest. It is front-loaded with the core action. A slightly more concise version might be possible, but the length is justified given the tool's behavior and the need to prevent misuse (e.g., reporting external tools).

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

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

Despite having no output schema, the description explains the primary return (claim_token) and the later status/read flow. It also covers rate limits, free usage, and the daily digest process. The tool has nested objects (context) and an enum (type), but the description complements these by explaining the overall purpose and edge cases. The completeness is high for this tool's complexity.

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

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

While the schema already provides 100% coverage for parameter descriptions, the tool description adds meaningful workflow context for the claim_token parameter: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' This clarifies how parameters interrelate (e.g., claim_token used alone without other arguments), which is not evident from the schema alone.

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's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team) and the action (sending feedback). It also distinguishes the tool from sibling tools by specifying it is only for this Pipeworx connection's tools, not other MCP servers.

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: '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: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This covers both positive and negative usage scenarios.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, caching window (5min-1h), and that it's derived from aggregate counts. 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 concise (~100 words), well-structured with bullet points for use cases, and front-loaded with the core function. Every sentence adds value without redundancy.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description completely covers what it returns, the source, caching behavior, and use cases. No gaps for an agent to understand its behavior.

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

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

Schema coverage is 100% with enum and description. The tool description adds interpretive guidance: shorter windows show 'hot right now', longer windows show 'steady-state demand'. This goes beyond the schema, justifying a score above the baseline of 3.

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

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

The description uses a specific verb ('Returns') and clearly identifies the resource: top tools, top packs, and call volume over a window. It distinguishes from siblings by focusing on aggregate trending data rather than individual tool discovery or queries.

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?

Three explicit use cases are provided, helping the agent decide when to invoke the tool for trend analysis, verification, or alignment. However, it does not explicitly state when not to use it or mention 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive context: algorithms (monotonicity checks, partition sum), semantic anchor (Jaccard similarity threshold), partition filter (placeholder fraction), fill check (book depth vs last trade). It fully discloses limitations and response structure. 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 lengthy but well-structured: overall purpose, then mode details, then algorithmic details, then response format. Every sentence adds value for a complex tool. Minor conciseness improvement possible (e.g., grouping fill check details) but still efficient.

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

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

Given the tool's complexity (multiple modes, algorithms, response fields, fill check) and no output schema, the description covers usage, behavior, output structure, and edge cases (e.g., placeholder filter). References sibling tool for custom sizing. Complete for effective agent usage.

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% but the description adds meaning: explains event mode vs topic mode, gives examples of slugs and seed questions, and clarifies that no args triggers trending_scan. This goes far 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 states a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) with distinct use cases, and explains what each does. No ambiguity.

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

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

Explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains when cross-event mode is better ('catches ... patterns that single-event misses') and provides format examples. No gaps.

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 read-only and idempotent behavior, and the description adds extensive behavioral context: 1h KV caching, edge calculation with slippage, Kelly fractions, movement warnings, and detailed segment breakdowns. 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 long but well-structured, front-loading the purpose and then detailing segments and knobs. Every sentence adds value given the tool's complexity, though minor condensation is possible.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, diagnostics), return fields, and filter mechanics, making it complete for agent 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?

With 100% schema coverage, baseline is 3, but the description adds significant meaning beyond the schema, especially for tradeable-edge knobs and min_partition_leg_kelly partition behavior, justifying a higher score.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb 'scan' and resource 'Polymarket markets', and distinguishes itself from siblings by detailing three model families and knobs.

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 the use case 'what should I bet on today' and notes Fed bets exclusion and caching. While it doesn't contrast with siblings directly, the context provides clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds significant behavioral context: history bounded by 60-day TTL, snapshot gaps, decay computation from daily closes, and limitations on history depth. 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?

Description is dense but front-loaded with the core purpose and question answered. It includes structured response fields and limitations. Somewhat verbose but each sentence adds value. Could be slightly more concise.

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 (time-series, telemetry, decay computation) and lack of output schema, the description thoroughly covers input parameters, response structure (tracked, expired, snapshot_dates), and limitations (TTL, snapshotting start, decay computation). Adequate for agent to invoke correctly.

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

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

Input schema covers both parameters with basic descriptions, but the tool description adds valuable detail: days lookback defaults and limits, window examples, and how they affect snapshots. Since schema_coverage is 100%, baseline is 3; description raises it to 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 the tool's function: 'edge persistence and decay telemetry' and answers the specific question about edge age and shrinkage. It distinguishes itself from siblings by focusing on persistence and decay, not just raw edges.

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

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

Description explains when to use the tool (to understand edge persistence and decay telemetry, distinguish fresh vs old edges) and implicitly contrasts with raw edge tools, but does not explicitly state when not to use it or mention 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 indicate read-only, idempotent behavior. Description adds that it walks the order book ladder, computes various fill metrics, and identifies risky legs. 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 detailed but verbose. It uses structural elements like REQUIRES, SINGLE-MARKET, BASKET to organize content, but some sections could be condensed without losing meaning.

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 thoroughly lists return fields for both modes, including specific metrics and warnings. It covers key risks like thin legs and forced directional risk, making it complete for decision-making.

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

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

Schema description coverage is 100%, so parameters are already documented. Description adds context beyond schema, such as the interpretation of size_usd for basket mode as settlement notional and default side logic, providing additional clarity.

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 checks realizable-vs-theoretical edge against live order book depth, with distinct modes for single-market and basket. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by its specific risk assessment role.

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

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

Explicitly advises when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Also warns about risks like partial basket fills converting an arb into an unhedged directional position.

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

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

Beyond readOnly/idempotent annotations, the description discloses the matching algorithm (token-overlap, keyword-based), the fact that pairing_unverified is set whenever pairs are returned, the gross-vs-net fee caveat, null semantics for temporal_alignment, and which legs are never paired (unknown metric_type/match_subtype). These are material behavioral traits an agent must know before trusting the numbers.

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 it is deliberately sectioned (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every block addresses a real decision or risk, especially given there is no output schema. The purpose is front-loaded in the first sentence, and the labels make it scannable; still, the volume of caveats borders on overwhelming and could be trimmed.

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

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

With no output schema and three optional params, the description carries the full burden of return semantics, and it covers leg prices, top_spreads_pp direction (Kalshi − Polymarket), compatibility codes, per-entry flags, skipped counters, temporal alignment null behavior, and fee disclosures. An agent has enough to interpret results safely and correctly without ever seeing the actual payload structure.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side and by spelling out the pre-mapped shortcuts in context. The full list of topic values and the 'auto-fetch the matching event' behavior go beyond the schema's simple type strings.

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

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

The first sentence states a specific verb ('Cross-venue spread') plus both resources (Kalshi and Polymarket) and the object ('same resolving question'). The two-mode description and the caution 'pre-mapped ≠ tradeable' further pin down what the tool computes, distinguishing it from single-venue siblings like polymarket_edges.

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

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

The description explicitly presents TWO MODES with when to use each: topic shortcuts for 10 pre-mapped macros and explicit ticker/slug for custom pairings, noting both run the same matcher. It warns that most pre-mapped topics currently return compatibility warnings ('pre-mapped ≠ tradeable'), giving clear expectation-setting. It does not, however, name any sibling tool as an alternative, so cross-tool selection guidance is only implicit.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by specifying scoping and listing behavior (omit key to list all). No contradictions. The behavioral context is sufficient given the annotations.

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

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

The description is well-structured and front-loaded. Each sentence serves a purpose: defining action, providing context, scoping, and pairing with siblings. Slightly lengthy but appropriately detailed 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 no output schema, the description could mention return format, but it adequately covers the main functionality. Annotations fill gaps for safety. The description is practically complete for a retrieval tool with good annotation support.

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% coverage with a description for 'key'. The description adds meaning beyond the schema: explains that omitting the key lists all keys, provides examples, and clarifies usage context. This is valuable supplementary information.

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

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

The description clearly states the tool's function: retrieve a saved value or list all keys. It uses specific verb ('Retrieve') and resource ('value previously saved via remember'), and distinguishes it from siblings (remember, forget) by explaining pairing.

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

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

The description provides explicit use cases ('look up context the agent stored earlier') and context (scoped to identifier). It implies pairing with remember and forget but does not explicitly state when not to use, though the differentiation is clear.

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

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

The description mentions mark_read:true flags events as read, a state change, but annotations set readOnlyHint=true, indicating no write operations. This contradiction reduces transparency to 1.

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?

Concise 6-sentence description with front-loaded purpose. No fluff, every sentence adds essential information. Well-structured for quick comprehension.

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 details return fields. Covers all 5 parameters (all optional) with usage examples. Mentions polling and external feed. Complete for a read-oriented tool given the context.

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

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

Adds significant value beyond the schema: explains type example (sec_8k), since format (ISO timestamp), limit range (1-200, default 50), and mark_read behavior. Schema coverage is 100%, and description enriches every parameter.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying returned fields (source, citation_uri, raw payload). It distinguishes from sibling tools like subscribe or list_subscriptions which manage subscriptions rather than read events.

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 filtering options (type, since) and mark_read/unread_only behavior. Mentions polling works and an alternative external URL for scripts/dashboards, aiding usage decisions. Lacks explicit when-not-to-use scenarios but covers key patterns.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds operational detail: fans out to three sources in one parallel call, GDELT→GNews fallback, USPTO patent soft-fail, and return format with citation URIs. 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?

Front-loaded with example queries. Two paragraphs, each well-structured. Slightly long but every sentence adds necessary context. Could be tightened slightly but remains clear.

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, but description specifies return format (changes[] grouped by source + total_changes + pipeworx:// URIs). For 3-param tool with no nested objects, it's fully 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 covers all 3 parameters with descriptions. Description adds value: explains value accepts ticker or CIK, since accepts ISO or relative with examples ('7d','30d','3m','1y'), and recommends typical window ('30d' or '1m').

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 specifies exact purpose: change feed for a company in a time window. Uses concrete examples like 'What's new with X' and explicitly distinguishes from sibling tool 'entity_profile' for static profiles.

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

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

Provides clear when-to-use (queries about updates/news) and when-not-to-use (use entity_profile for static profile regardless of window). Also explains fallback behavior between GDELT and GNews.

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

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

Description adds behavioral context beyond annotations: key-value scoping by identifier, persistence details (authenticated vs anonymous). 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?

Three well-structured sentences, front-loaded with purpose, no wasted words. 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 all necessary context: purpose, usage, persistence, pairing with siblings. Complete for a simple 2-parameter 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 both parameters with descriptions (key, value). Description adds example patterns but does not significantly add meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for later reuse, with specific verb ('save') and resource ('data'). It distinguishes from siblings 'recall' and 'forget', making purpose unambiguous.

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

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

Explicitly tells when to use (discover something worth carrying forward) and mentions alternatives ('Pair with recall to retrieve later, forget to delete'). Provides clear 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, destructiveHint=false. The description goes far beyond these by disclosing graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicit unresolved output ('stated explicitly under unresolved rather than omitted'), ambiguity handling (figi_candidates), source labeling, and the fact that this tool replaces 2-3 manual 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 long but well-structured: it leads with example queries and a one-sentence purpose, then breaks down supported types and caveats. Every sentence carries meaningful behavioral detail. It loses a point for density and some redundancy (e.g., the 'which is the correct answer to an issuer name' clause could be trimmed), but it remains front-loaded and organized.

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

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

There is no output schema, so the description carries the full burden of explaining return behavior — and it does: 'returns figi_candidates', 'unresolved', 'RxCUI + ingredient + brand… citation', and ownership info (parent/ultimate-parent/children). It also covers input handling, failure modes, and edge cases (ISIN-to-LEI for non-US issuers). An agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. For 'value' it provides critical input rules — 'Pass the ENTITY NAME ONLY… never the question's full noun phrase… trailing security-class words match nothing' — with a concrete bond example. It also explains accepted identifier formats (ticker, CIK, ISIN) and the drug-type behavior, which are not evident from the schema alone.

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

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

The description opens with concrete example queries ('What's the ticker for…' / 'find the CIK for…') followed by a precise verb+resource statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from siblings via 'Use FIRST whenever you have a name but need an ID', so an agent can tell exactly when this tool applies.

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

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

Explicit when-to-use guidance is front-loaded: 'Use FIRST whenever you have a name but need an ID.' It also gives when-not-to behavior — 'when a name matches more than one instrument it asserts nothing and returns figi_candidates to pick from' — which tells the agent how to interpret ambiguous cases instead of guessing. The type-specific details (company vs drug) further instruct which input kinds are accepted.

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 safe read-only, idempotent, non-destructive behavior. The description adds process details (probing with ai_visibility_check) and output structure (ranked list with score, confidence, signal density), which are transparent about expected behavior beyond 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?

Three sentences with no wasted words. The purpose is front-loaded, followed by mechanism and example usage. 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?

The description explains all necessary aspects: what it does, how it works (probes each entity), what it returns (ranked list with metrics), and example use case. No output schema exists, but the description covers return values adequately.

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

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

Schema coverage is 100%, but the description adds crucial context: first entity is the 'subject' for narrative, rest are competitors. It also clarifies default model and apiKey usage. This adds meaningful 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 it compares AI visibility across multiple entities, using ai_visibility_check, and ranks by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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?

The description explicitly targets competitive AI-marketing audits and implies when to use it. It does not provide explicit when-not-to-use or exclude alternatives, but the context from sibling tools and the description's mention of 'probes each entity with ai_visibility_check' provides sufficient guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds crucial behavioral details: fans out to deps.dev and bundlephobia, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts.

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?

Single dense paragraph, but each sentence adds value. Could be slightly more structured with bullet points for the return fields, but it's efficient and front-loaded with the core purpose.

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

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

No output schema, but description lists all return fields (summary block, per-advisory detail, links, alternative versions). Covers ecosystem constraints, failure modes, and latency expectations. Fully sufficient for an agent to understand tool behavior.

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

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

Schema description coverage is 100% (package and version described). Description adds value by mentioning scoped packages accepted and that version defaults to latest. Provides useful context beyond schema types.

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's a composite check for npm packages covering license, advisories, version history, bundle size, and tree-shaking. The verb 'scan' and resource 'dependency' are specific, and the description distinguishes it from sibling tools by focusing on npm ecosystem.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies npm-only in v1 and mentions alternatives for other ecosystems (PyPI, Maven, etc.) via deps.dev.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds that it returns a number unaffected by suffering, but this is mostly flavor. 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?

Single sentence, front-loaded with the action, no wasted words. Highly concise.

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

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

The tool is simple, annotations cover safety, and output schema exists. The description is complete enough for an agent to understand what the tool does.

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% description coverage, so description adds little beyond restating the parameters. The joke about 'It will not help' is not substantive semantic 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 uses a specific verb ('Submit') and resource ('scream into the void') and clearly distinguishes from all sibling tools, none of which involve screaming.

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

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

The description implies usage (when you want to express frustration) but provides no explicit guidance on when to use vs when not, nor mentions any 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 details beyond annotations: embedding model (BGE-base-en), chunking (cosine over 500-char overlapping windows), character cap (200K chars with truncation flag), and offset for verification. 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?

Concise but informative: opens with purpose, then usage guidance, then technical details. Every sentence adds value 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?

Given the tool's moderate complexity and rich annotations, the description covers purpose, use cases, technical behavior, and limits. No output schema exists, but return format (passages with offsets/scores) is explained adequately.

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

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

Schema description coverage is 100% for all 3 parameters (text, query, limit). The description does not add significant new meaning beyond the schema descriptions, so baseline 3 is appropriate.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes itself from siblings by mentioning it pairs with ask_pipeworx_grounded for grounding over passages.

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 when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded' for an alternative workflow, providing clear when-to-use and when-not-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 behavioral context beyond the annotations. Annotations indicate idempotentHint=true and destructiveHint=false, but the description explains authentication requirements, delivery channel options, SMS caps, webhook signing, and auto-disable behavior. 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 well-structured with bullet points and clear sections. It front-loads the core purpose. While slightly lengthy, every sentence adds value, but minor trimming 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 the tool's complexity (3 params including nested objects, no output schema), the description is exceptionally complete. It covers the return value (subscription id), authentication requirements, all supported types with examples, delivery channels with constraints, and operational details like auto-disable.

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 description adds substantial meaning to all parameters. It provides concrete examples for each type in the 'type' enum, detailed examples for 'params' (e.g., sec_8k and polymarket_edge), and comprehensive explanation for 'delivery' including constraints and validation rules.

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 creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by explaining the subscription creation purpose.

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

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

The description provides explicit context on when to use this tool (to set up monitoring), required authentication (Pipeworx OAuth account), and details on supported types and delivery. It could be improved by contrasting with when to use alternatives like recent_alerts or unsubscribe, but overall it offers clear usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description's addition of output format details (category-bucketed examples with tool and arguments) enhances transparency without redundancy.

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 example queries and structured to explain purpose, usage, and output. While a bit verbose (multiple lines), every sentence earns its place by providing actionable guidance.

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 covers what the agent needs: when to use, how to call, what the response contains, and even lists example topics. No gaps remain.

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

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

Schema coverage is 100% with a clear description for the 'topic' parameter. The description adds practical nuance: omitting topic gives a full spread, while passing a topic focuses results. This goes beyond the schema's basic enumeration.

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 the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by being the first tool to use when unfamiliar with 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 instructs to use this tool FIRST when the agent does not yet know what Pipeworx can do, and explains how to call it with no arguments or with a specific topic. This differentiates it from sibling tools like ask_pipeworx or compare_entities.

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, destructiveHint, and idempotentHint. The description adds ownership enforcement, clarifies deactivation vs. deletion, and notes that historical events remain available. 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 sentences with no wasted words. Each sentence conveys essential information: the action, constraints, and side effects.

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 is adequate for a simple mutation with one parameter and no output schema. It covers ownership, side effects, and relationship to another tool. However, it could mention idempotency explicitly, though annotations cover it.

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 'id' as 'Subscription id (uuid) returned by subscribe.' The tool description does not add significant meaning beyond that, meeting the baseline of 3.

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

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

The description clearly states 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying the deactivation behavior and linking to 'recent_alerts' for historical events.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains that deactivation keeps historical events accessible via 'recent_alerts.' It implicitly guides when to use the tool but lacks explicit when-not or alternative distinctions for a perfect score.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavioral context: the exact meaning of 'could_not_verify' (check did not happen, must not be shown as evidence) and 'unsupported' (no source found). It also explains the two pipeline paths (SEC EDGAR vs grounded fallback). Annotations are not contradicted.

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

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

The description is long but every section earns its place: trigger phrases, usage scope, pipeline routing, return types, and crucial error semantics. It is slightly repetitive at the start but well-structured and front-loaded. Overall 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 no output schema, the description fully explains the return value (verdict enum, actual value with citation, reasoning) and covers the important edge cases of 'could_not_verify' and 'unsupported'. It also gives performance context. The combination of annotations, schema, and description leaves no major gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it mentions tolerance only indirectly via the financial math path. The schema descriptions are already rich, so no additional parameter guidance is necessary.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, returning a verdict. It gives explicit trigger phrases and distinguishes itself from sibling tools by being a focused fact-checking tool rather than general Q&A or research.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and outlines the fallback path for non-financial claims. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls short of the highest anchor.

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