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 readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it routes to various tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. It also implies the grounded version is more hallucination-resistant, disclosing a limitation. This exceeds the bare annotation baseline.

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

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

The description is relatively long but front-loaded with the key instruction and packed with examples and explicit usage boundaries. Each sentence serves a purpose: domain list, routing behavior, trigger phrases, and sibling differentiation. It earns its length for a default entry-point tool, though it could be trimmed slightly.

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 and only one real semantic parameter, the description fully explains what the tool does, what it returns, when to use it, and how it relates to siblings. It even clarifies that breaking news is covered. This is a complete picture for an agent to select and invoke it correctly.

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

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

The input schema already documents all six parameters as aliases of 'question' with 100% coverage, so the description need not repeat them. The description adds general guidance about the type of natural-language questions to ask, but no parameter-specific details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific purpose: to route questions to the right tool among 5,529 tools across 1,455 sources and return structured answers with citations. It uses strong verbs like 'routes' and 'returns' and explicitly contrasts itself with siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and distinguishes from alternatives by saying 'Step up only when needed' for grounded or deep research. Includes concrete examples of appropriate queries. This clearly tells the agent when to use it vs 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, open-world, and non-destructive behavior. The description adds the beta testing context: candidate routing improvements are activated live, currently none active, and that it matches ask_pipeworx exactly. It also addresses the potential misconception about falling back, adding valuable context 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?

The description is three sentences but somewhat wordy with parenthetical details. It front-loads the key information and each sentence serves a purpose, though it could be tightened. Good structure with a clear flow from identity to usage.

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 router, the description covers identity, current state, usage, and behavior. It does not describe the response format, but as a beta of an existing tool with the same response shape, it is implied. Given annotations and sibling context, it is reasonably complete.

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

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

Schema coverage is 100% with descriptions for each alias. The description confirms same arguments as ask_pipeworx but does not add detail beyond the schema. Since the schema already documents all parameters, the description adds minimal extra meaning, warranting the baseline 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 identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and current state, making the tool's purpose specific and differentiating it from siblings.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, contrasting with the stable version. It also clarifies that it is a full working router, not a fallback, and that results are compared to decide merges. This provides clear when-to-use guidance and addresses alternatives.

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

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

The description goes well beyond the annotations (readOnlyHint=true, idempotentHint=true): it discloses the refusal mechanism with specific refusal_reason values, states the answer is extracted only from tool results, and mentions the one extra LLM call overhead. This provides critical behavioral context that annotations do not cover. 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 front-loaded with the core value proposition ('Hallucination-resistant answer mode'), then efficiently covers routing, output shape, refusal reasons, use cases, and cost. Every sentence contributes meaningful information; there is no fluff or redundant repetition of the tool name.

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

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

Despite having no output schema, the description fully specifies the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all refusal reasons. It also explains the underlying tool routing, source count (5,529 across 1455 sources), and cost tradeoff, making the tool's behavior fully predictable for an agent.

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

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

The schema covers 100% of parameters, with all six being aliases for the 'question' parameter and clearly described. The description does not add new parameter-specific semantics, but it contextualizes how the question is used ('fills arguments'). Per calibration, high schema coverage gives a baseline of 3, and no stronger justification exists for 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' a specific verb+resource+qualifier. It clearly states what the tool does: routes like ask_pipeworx, fetches data, and extracts answers using ONLY the tool result. It also distinguishes itself from the sibling ask_pipeworx by emphasizing evidence and refusal behavior.

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

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

The description explicitly says when to use it: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a when-not: 'prefer ask_pipeworx for casual lookups,' and notes the extra LLM call cost. This is clear usage guidance with an explicit alternative.

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

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

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond these by explaining the research process (decomposes, routes, parallel), the output format (findings packet with verbatim evidence, confidence, gaps[]), the 'never invented' honesty policy, citation resolvability guarantee, semantic excerpting behavior, and latency expectations (15-60s, up to ~90s). This is rich behavioral context beyond the annotations.

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

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

The description is fairly long, but every sentence earns its place by conveying critical usage guidance, behavioral expectations, and alternatives. It is front-loaded with the most important operational constraint (account required). While dense, it avoids fluff and is structured as a coherent set of conditions and behaviors. Slightly over-long but justified by the tool's complexity.

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

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

For a complex tool with no output schema, the description thoroughly covers the return format, gaps[], contradictions[], citation behavior, hop field, latency, pairing with siblings, and depth-tier semantics. It tells the agent exactly what to expect and when to choose this tool. The context is complete enough to select and invoke correctly, including edge cases like empty gaps[] for non-structured topics.

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 both parameters well-documented: question described as natural language with broad/multi-part fine; depth enum describes the three levels and their behavioral implications. The description adds value by explaining the 'standard' and 'thorough' depths include gap recovery and contradictions[] scans, and that 'thorough' is paid. Since schema already covers the parameter basics, the extra detail about depth behavior and cost elevates it above baseline.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, distinguishing it from open-web search and sibling tools like ask_pipeworx. It specifies the verb (research), resource (structured data sources), and scope (broad/multi-part questions), and explicitly contrasts with alternatives.

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: 'Best for broad/multi-part questions over structured data' and explicitly names alternatives and exclusions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account requirements and depth tiers, giving clear context for choosing this tool.

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

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

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

The description discloses behaviors beyond annotations: it fans out across multiple APIs, mentions that patents soft-fails until reactivated, explains the news fallback (GDELT→GNews), and notes unsupported entity types. 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 a single paragraph of ~200 words. It is front-loaded with examples but could be more structured (e.g., bullet points). Every sentence adds value; no waste.

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 complexity of the tool (multiple sources, fallbacks, soft-fails) and the absence of an output schema, the description covers all essential aspects: what is returned, how to format input, known limitations, and fallback behavior. It is fully 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that type is only 'company' and that value can be ticker or zero-padded CIK, and reinforces that names are not supported. This provides practical usage context 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 that the tool provides a full cross-source profile of a US public company. It lists specific example queries and explicitly enumerates the data sources and return fields, which distinguishes it from siblings like compare_entities or resolve_entity.

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

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

The description explicitly advises: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name).'

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 annotations (readOnlyHint, openWorldHint, idempotentHint), the description details safety fields (compatibility_warning), temporal alignment, and skipped cross types. It explains the logic behind matched pairs and when spreads are meaningless, offering substantial behavioral 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 dense and front-loaded with the core purpose. Every sentence adds value, though it is somewhat long. The structure (modes, response details, safety, temporal, caveats) is logical and 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 complexity of cross-venue spread computation, the description is remarkably thorough. It covers all modes, edge cases (compatibility warnings, temporal alignment), and return fields. No output schema exists, but the verbal explanation is sufficient for an agent to understand inputs, behavior, and outputs.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the two modes, override behavior, and response structure (leg-by-leg prices, top_spreads_pp, safety fields). This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool computes 'Cross-venue spread between Kalshi and Polymarket' for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by specifying the exact venues and the two operating modes (topic and explicit).

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

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

The description explains when to use the tool (to compute arbitrage spreads) and warns that pre-mapped topics often return compatibility_warning, indicating not all are tradeable. It provides context for interpreting results but does not explicitly mention when not to use or list alternative tools.

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

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavioral details: identifiers are source-labelled, unresolved ones are explicitly stated, enrichment degrades gracefully if GLEIF/OpenFIGI are down, and internal cascading replaces multiple manual lookups. These details give an agent a strong mental model of what happens during 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 long but information-dense. The opening examples may be a bit verbose, but they effectively convey the range of user intents. The SUPPORTED TYPES structure makes it scannable, and every sentence contributes either purpose, usage, or behavior.

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

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

Given no output schema, the description covers key runtime behavior: output labeling, unresolved identifiers, citation links, and failure degradation. It also clarifies the full input space for both entity types, making it complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already covers the two parameters with 100% coverage and examples. The description adds value by explaining the 'company' cross-source identity spine and the 'drug' RxNorm/RxCUI output, plus input variations (ticker, CIK, name, brand/generic). This is helpful context beyond the schema, though the schema alone is quite clear.

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

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

The description opens with concrete user phrases and immediately states the core purpose: resolving a user-spoken name to canonical/official identifiers. It clearly distinguishes this from siblings by positioning it as the first step when a name needs to become an ID, with explicit supported types (company, drug).

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives clear usage context. However, it does not name alternative tools or state explicit when-not-to-use conditions, so it stops short of a full 5.

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

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

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