Buzzword Density

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

Annotations already declare readOnlyHint and idempotentHint as true, so the safety profile is clear. The description adds context about external API calls, default model (free), BYO key for Anthropic, and return format (score, confidence, signals, raw_response). This is sufficient 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 concise (two paragraphs) with front-loaded core purpose. Every sentence adds value, no repetition or fluff. Structure is logical: function, then technical details, then use cases.

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 the description explicitly mentions the return format (per-model {score, confidence, signals, raw_response} + combined view). All input parameters are explained. It covers the main aspects adequately for a moderate-complexity tool.

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

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

Schema coverage is 100%, so each parameter has a description. The description text adds value by explaining the _apiKey flow, default model choice, and context disambiguation, which goes beyond the schema's 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 it probes LLMs for knowledge and scores visibility (0-100) per model. It specifies the verb 'probe' and resource 'LLMs for business/brand/product/topic', and distinguishes from siblings like ask_pipeworx and scan_competitor_ai_presence through unique output and use cases.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use optional parameters (e.g., _apiKey for Anthropic). However, it does not explicitly contrast with sibling tools or state when not to use, leaving some ambiguity.

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 meaningful context: it auto-routes to 5,798 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description front-loads the key instruction and includes useful examples, but it is noticeably repetitive: 'START HERE for most questions — even if web search could also answer it. Examples: ...' is repeated multiple times. Not every sentence earns its place.

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

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

Despite no output schema, the description explains the return format ('structured answer with stable pipeworx:// citation URIs') and the routing/fill-arguments behavior. This is sufficient for a one-required-parameter open-world question tool, though it lacks detail on failure modes or latency.

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 all six parameters are fully documented as aliases for the single natural-language question. The description does not add parameter semantics beyond examples of good questions, 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 names a specific action ('Routes the question to the right one of 5,798 tools...') and a clear resource (Pipeworx), and it explicitly distances itself from generic web search. It does not, however, differentiate from sibling Pipeworx variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

Gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH...', 'Use whenever...', and 'START HERE for most questions'. It names web search as the main alternative but doesn't state exclusions or when a sibling/other tool should be chosen instead.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context: candidate routing improvements may be enabled live, the tool currently matches ask_pipeworx exactly, and it falls back to nothing because it is a full working router rather than a stub. This goes beyond the annotations without contradicting them.

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

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

The description is moderately sized but every sentence contributes meaningful context: beta status, equivalence to ask_pipeworx, current candidate state, usage guidance, and the absence of a fallback. It is front-loaded with the most important facts and does not waste words.

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

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

For a universal router with no output schema, the description is nearly complete: it states the tool's behavior, current state, relationship to the stable sibling, and that the response shape matches ask_pipeworx. An agent can confidently select and invoke it, though a concrete example of a routed question would add a bit more ground truth.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for the required 'question' parameter. The description adds only that the tool accepts the same arguments as ask_pipeworx, which is useful but not necessary for understanding the parameters. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing improvements, making its purpose and relationship to ask_pipeworx unambiguous.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It gives a clear usage context, though it does not explicitly state when not to use it or compare it to ask_pipeworx_grounded.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial behavioral detail beyond that: it extracts answers only from the tool result, refuses rather than guesses, returns a structured object with evidence and confidence, and lists specific refusal reasons. It also discloses the extra LLM call cost, which is exactly the kind of operational behavior an agent needs to know.

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

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

The description is dense but every sentence earns its place: what the tool does, how it works, return shape, refusal shape, when to use it, and when not to use it. It is front-loaded with the most decision-relevant information, and the cost tradeoff is placed last as a secondary consideration.

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

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

For a tool with no output schema, the description fully compensates by specifying both the success return shape and the refusal return shape, including all possible refusal reasons. It also covers routing behavior, source scope, and the cost/usage tradeoff against its sibling, so an agent has everything needed to 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 schema has 100% description coverage, with every parameter alias (q, text, input, query, prompt) explicitly mapped to 'question' and a natural-language description. The tool description itself adds little parameter-specific meaning, but the schema fully carries that burden, so a baseline 3 is appropriate.

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

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

The description opens with a specific, functional label—'Hallucination-resistant answer mode for high-stakes reads'—and immediately distinguishes this tool from ask_pipeworx by naming it and contrasting their behavior. The verb+resource pairing ('picks the right tool... fetches the data... EXTRACTS the answer') makes the tool's role unmistakable.

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

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

Explicit when-to-use guidance is present: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete example domains. It also states the alternative preference directly: 'prefer ask_pipeworx for casual lookups,' giving the agent a clear decision rule.

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 extensively discloses behavioral traits: resolution process, classifier fan-out, response shapes, safety mechanisms (low_confidence_match, market_closed_or_inactive), wide spread handling, resolution-rule risk. Annotations already indicate read-only and idempotent, and the description adds significant context beyond annotations without contradiction.

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

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

The description is very long and detailed, covering multiple aspects with examples and caveats. It is front-loaded with the main purpose, but the length reduces conciseness. While all information is relevant, some redundancy could be trimmed. Still, it is well-structured with clear sections.

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, response shapes, safety modes, no output schema), the description is remarkably complete. It covers input formats, behavioral edge cases (closed markets, wide spreads, resolution rules), and explicit guidance on inspecting match confidence and response fields.

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

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

Schema coverage is 100%, but the description adds substantial value: examples for market parameter, clarification of depth (quick vs thorough), explanation of include_raw (summarized vs full payloads), and typical use guideline for include_raw. This goes well beyond the schema's property 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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edge_tracker or polymarket_edges, which have similar domain focus.

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: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It advises inspecting market_match_confidence before trusting analysis and explains safety behaviors. However, it does not explicitly state when to use alternatives or when not to use this tool.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds details on return values (count, score, severity, flagged terms) and optional roast, enhancing transparency without contradiction.

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

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

Single sentence with all key elements: action, dictionaries, output, optional feature. No redundant words.

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

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

Given output schema presence, description covers tool purpose, parameters, and return information sufficiently for a simple analysis tool.

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

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

Schema coverage is 100%. Description adds meaning by listing output metrics and explaining roast parameter effect, surpassing 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?

Description clearly states the tool analyzes text for overused industry jargon using specific dictionaries, and lists return metrics. Distinct from sibling tools which are unrelated.

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 implies use for analyzing buzzwords in text, with optional roast. No explicit when-not-to-use, but sibling tools are different domains, so context is clear.

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

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

Annotations already indicate a safe read operation (readOnlyHint, openWorldHint, idempotentHint). The description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting, and citation URIs, which enrich 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 a single paragraph that is information-dense but well-organized, starting with trigger phrases and purpose, then entity details. It is concise yet comprehensive, though could be slightly improved by splitting into shorter sentences.

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 2 parameters and no output schema, the description fully covers what the tool does: data retrieved (financial metrics for companies, adverse event counts for drugs), sorting, citation URIs, and efficiency benefits. 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 has 100% coverage with two parameters. The description adds meaning by explaining that for 'company' type values should be tickers/CIKs, and for 'drug' type values should be drug names, with concrete examples. This goes beyond the schema's enum and array descriptions.

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

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

The description clearly states that the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one call, and distinguishes itself from sequential single-pack lookups by providing trigger phrases like 'compare X and Y'. It also specifies the data retrieved for each entity type.

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 recommends preferring this tool over sequential single-pack lookups when comparing entities, and differentiates between 'company' and 'drug' types. It lacks explicit exclusions but provides clear usage context.

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

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

Annotations already carry the readOnly/idempotent safety profile, so the bar is lower; the description still adds rich behavior: decomposition into facets, parallel routing to 5,798 tools, findings packets with confidence/source/citation, explicit gaps array, contradiction scans, semantic excerpting, latency ranges, and paid-depth restrictions. There is no contradiction with the readOnlyHint.

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 definition is dense and information-rich, front-loading the account gate and the ask_pipeworx alternative before the core capability. It is longer than average, but nearly every sentence contributes behavioral or routing detail; minor redundancy in mentioning ask_pipeworx twice keeps it from being a 5.

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

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

Since there is no output schema, the description correctly carries the return-value burden by naming the findings packet fields: verbatim evidence, confidence, source, fetched_at, pipeworx citation, gaps, contradictions, hop, and citation_uri. It also covers input scope, latency, auth requirements, and depth semantics, leaving no major gap for correct invocation.

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

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

Schema description coverage is 100% and both question and depth are well documented in the schema, so the baseline is 3. The description adds value by explaining depth-specific behavior such as gap-recovery hops, contradiction scans, the paid thorough tier, and expected latency beyond the schema's enum text.

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

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

The description states a precise verb-plus-resource: grounded multi-source research across Pipeworx's 1517 structured data sources, and explicitly says it is NOT open-web search. It also distinguishes itself from ask_pipeworx by positioning itself for broad/multi-part questions while directing single lookups to that sibling.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also warns about account requirements and tells agents to use ask_pipeworx if not signed in, preventing failed invocations.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results include full schemas and curated examples ready to call directly, enhancing transparency about the output format and readiness for invocation.

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 efficient: first sentence establishes purpose, then lists use cases, then explains output behavior. No redundant sentences; all information is essential and well-organized.

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

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

Despite lacking an output schema, the description fully explains the return value: top-N tools with names, descriptions, and full input schemas. For a discovery tool, this is complete and actionable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example queries and explaining that aliases (task, q, search, description) are accepted, plus indicates the limit parameter. This goes beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and provides a comprehensive list of domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific tasks.

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 'Call this FIRST when you have many tools available' and gives examples of when to use (browse, search, look up). Lacks explicit exclusion of alternatives but implies use for discovery rather than direct answers.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds extensive behavioral context: it is a single parallel call, it fans out to multiple sources, it soft-fails on the sunset USPTO PatentsView API, and it returns sources_used/sources_failed to distinguish "no data" from bugs. It also explains fallback behavior (GDELT to GNews) and the resolved:false case for private companies. No contradiction exists with the read-only/idempotent 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 it earns its length through dense, non-redundant detail covering triggers, preference rules, source fan-out, return fields, failure semantics, and accepted value formats. It is front-loaded with concrete user phrasings before moving to technical behavior. A slight deduction is warranted because the wall of text could be tightened without losing information, but there is no filler.

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

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

For a complex tool with no output schema, the description is remarkably complete: it enumerates all returned sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and explains what empty sections and sources_failed mean. It also covers input flexibility, private-company behavior, source fallbacks, and API sunset handling. An agent has enough context to invoke the tool and interpret its results without additional lookup.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that type accepts "company" or "ticker" interchangeably despite looking like a discriminator, gives concrete examples for value ("AAPL", "0000320193", "Moderna"), and explains how names resolve via SEC EDGAR. It also documents the private-company outcome, which affects interpretation of the return value rather than just the parameter format.

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 and resource: it "fans out across SEC EDGAR, XBRL, USPTO patents..." to produce a "full cross-source profile of a US public company." It distinguishes itself from chained single-source lookups by explicitly saying "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups." The trigger examples like "Tell me about X" and "brief me on Tesla" make the tool's scope immediately recognizable.

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 this tool: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also covers the alternative path (individual SEC/XBRL/news lookups) and clarifies edge-case behavior for private companies, saying they return resolved:false with an explicit notes line. This gives an agent clear routing guidance rather than leaving it to inference.

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

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

Annotations already include destructiveHint=true and idempotentHint=true, so the destructive nature is clear. Description adds 'clear sensitive data' context but does not elaborate on idempotency or consequences of deleting non-existent key. Minimal extra value 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?

Two sentences: first states purpose, second gives usage guidelines. No redundancy, efficient 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?

Simple tool with one parameter and clear annotations. Description covers purpose and usage. No output schema but delete operations typically don't need detailed return info. Could include error handling details but not essential.

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 description for the single parameter 'key'. Description does not add additional meaning beyond 'Memory key to delete' already in schema. Baseline 3.

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

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

Description uses specific verb 'Delete' and resource 'memory by key', clearly stating the action. It distinguishes from siblings 'remember' and 'recall' by specifying deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Mentions pairing with related tools. Does not explicitly say when not to use, but guidance is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions; all behavioral aspects are transparent.

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, well-structured paragraph that front-loads the core action and format, then lists use cases. Every sentence adds value; no wasted words.

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

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

Despite lacking an output schema, the description clearly states the output is a 'single text blob ready to drop at site-root/llms.txt', which is sufficient for a simple read operation. It covers purpose, usage, and output format 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%, so description adds little beyond schema. The description reinforces the purpose of 'url' (full URL to summarize) and mentions default/max for 'max_links', which is helpful but not a significant addition.

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 generates a production-ready llms.txt file for any URL, explaining the action (fetches, extracts, emits) and the format. It distinguishes itself from the many sibling tools by focusing on a specific, well-defined use case for AI crawler indexing.

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

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

Explicitly lists three practical use cases: getting a client's site indexed, drafting for own project, and auditing competitors. While it doesn't explicitly state when not to use, the provided scenarios give clear guidance.

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

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

Annotations already mark it read-only/idempotent; description adds that it defaults to active subscriptions and specifies the return fields, enhancing transparency.

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

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

Two sentences: first covers purpose and output, second covers usage. No extraneous words, information is front-loaded.

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

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

Complete for a simple list tool: documents return fields, parameter behavior, and usage context. No output schema needed given the list of fields.

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

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

Schema covers 100% of the single parameter with description; tool description only reinforces schema content without adding new semantic value.

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

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

Explicitly states the tool lists active subscriptions and enumerates the returned fields (id, type, etc.), clearly distinct from subscribe/unsubscribe 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?

Directly advises using this tool to review monitoring before adding more subscriptions or to find an id to cancel, providing clear when-to-use context.

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

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

Annotations only state readOnlyHint:false and destructiveHint:false, but the description adds crucial behavioral details: returns a claim_token when filed without an account, supports later retrieval with status/changes, rate limit of 5/day, free, and no quota impact. It also instructs to describe issues without pasting end-user prompts. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: the first line is a clear purpose, followed by usage triggers, exclusions, token behavior, rate limit, and quota note. No redundancy or filler. Front-loaded and well-organized for the 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?

Despite no output schema, the description fully explains return behavior (claim_token on filing; status/changes on later call). It covers prerequisites (no account needed, but token), limits, and context about what to include. Given a 4-param tool with nested object and no output schema, this description is complete enough for an agent to invoke correctly.

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

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

Schema covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by mapping enum values to real scenarios (bug, feature, data_gap, praise) and by giving extra guidance on the message param ('don't paste the end-user's prompt') and how to use claim_token effectively. This 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by specifying it is for reporting issues about Pipeworx tools only, 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?

Extensive when-to-use guidance is given for each feedback type (bug, feature/data_gap, praise). It explicitly says when NOT to use ('if the tool came from a different MCP server... file it with that server instead'), plus provides the alternative. This fully covers usage 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by disclosing data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h). 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?

Around 120 words, well-structured with bullet points. Front-loaded with main functionality. Minimal waste, though could be slightly shorter. Still very 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?

Despite no output schema, description adequately documents return values (top tools, top packs, total call volume). Covers caching, privacy, and parameter semantics. Complete for the tool's complexity and annotations.

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

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

Schema coverage is 100% with full description for the single parameter 'window'. The tool description adds no new info beyond what's already in the schema parameter description, so baseline 3 applies.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, using a specific verb ('returns') and resource. It distinguishes itself from siblings like 'discover_tools' by focusing on trending usage rather than available tools.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming popular tools, aligning use cases). The description explains window trade-offs (short for hot, long for steady-state). No explicit exclusions or alternatives, but guidance is clear.

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

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

Annotations declare the tool readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: scanning top markets, partition-sum checks with deviation thresholds, semantic anchor for cross-event pairs, placeholder filtering, fill check against live CLOB depth, and warnings not to trade if realizable_edge_pp ≤ 0. 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 a single paragraph but well-structured: starts with core purpose, then details each mode, then explains deeper logic (semantic anchor, partition filter, fill check). Front-loaded with the most important info. Slightly verbose but every sentence adds value; could be broken into sections for better readability.

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 (two modes, multiple checks, fill validation) and the absence of an output schema, the description covers all necessary aspects: it explains the logic of monotonicity violations and partition-sum checks, describes the response structure (opportunities[].gap_pp, suggested_trade, reasoning, partition_check, fill_check details), and references sibling tools for additional usage. Highly 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 parameter descriptions, but the tool description adds substantial meaning: it explains that event mode walks child markets for date-axis/threshold-axis ordering and partition check, and topic mode searches related events across the platform. It provides examples of acceptable inputs (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'). This greatly enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities), and method. Distinguishes three invocation modes (no args, event, topic) and their outcomes, setting it apart from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description gives explicit guidance on when to use each mode: 'Call with NO args for a trending scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode 'for a specific market' and points to polymarket_fill_risk for custom sizing. It lacks explicit 'when not to use' statements but provides clear context and alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: caching (1h KV), model family details, edge calculation, diagnostic fields, and tradeable-edge knobs. No contradictions.

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

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

The description is long but well-structured with clear sections (model families, tradeable-edge knobs, response top-level) and front-loaded purpose. Every sentence adds value, though some technical detail could be condensed.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics) and provides enough detail for an agent to understand all capabilities and limitations. Covers caching, edge calculation, filter knobs, and output fields.

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

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

Schema description coverage is 100% with all 9 parameters documented. The description adds value by explaining parameter interplay and rationale (e.g., slippage_pp discussion of thin depth, min_partition_leg_kelly behavior). Baseline 3 but elevated due to added insight.

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 and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear usage context: 'Built for "what should I bet on today"' and explains tradeable-edge knobs with guidance on when to apply them (e.g., 'Set to 2 to require tight books'). However, it does not explicitly state when not to use this tool versus 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 indicate readOnly=true, idempotent, non-destructive. The description adds critical details: history bounded by 60-day TTL, decay from daily closes (not intraday), and snapshot-on-cache-miss behavior. 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 purpose, then detailing response fields, and ending with limits. Every sentence adds value, though some technical details could be slightly more concise 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?

Even without an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) including field semantics. It covers limitations (TTL, intraday) and provides necessary context for using the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description reiterates days (default 14, max 30) and window (default '1wk') but adds usage context like 'clamp 2-30' and snapshot families. This adds marginal value beyond the schema.

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

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

The description explicitly states it provides 'edge persistence and decay telemetry' answering the key question of edge duration and shrinking. It uses specific verbs like 'track' (implied) and clearly distinguishes from sibling tools like polymarket_edges (raw data) and 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 gives a concrete use case: distinguishing fresh vs old wide edges. It implies when to use it but does not explicitly state when not to or mention alternatives. Context is clear enough for an agent to decide.

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 the tool is read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about thin books and forced directional risk. This goes well beyond what annotations provide.

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

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

The description is somewhat lengthy but well-structured with clear sections (SINGLE-MARKET, BASKET). It front-loads the essential purpose and requirements. Every sentence provides necessary detail; however, minor condensation could be achieved without loss of clarity. Still, it is appropriately informative.

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 two modes, 4 parameters, and no output schema, the description covers all critical aspects: input requirements, default behavior, return fields (including top_of_book, VWAP, slippage, verdict, capture_ratio, profit_usd, thin_legs, forced_directional_risk), and risk explanations. It is comprehensive for the agent to understand and 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 baseline is 3. The description adds value by explaining defaults (size_usd=1000, side default behavior in basket mode), clarifying how size_usd is interpreted differently for buys vs sells and single-market vs basket, and describing the auto-behavior for side in basket mode. This semantic enrichment justifies a 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes, and its purpose is reinforced by context signals (e.g., using before arbitrage signals). The verb and resource are specific and unique among sibling tools.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills lead to directional risk), and states requirements (one of `market` or `event`).

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 that matching is keyword/overlap-based rather than source-confirmed, that compatibility codes can be non-empty even when pairs are returned, that Kalshi's fee schedule is not modeled, and that unknown legs are never paired. This is substantial behavioral context that no annotation provides.

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 logically organized with labeled sections such as TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. Important operational warnings are front-loaded, and nearly every sentence adds value for a complex tool. It could be tightened slightly, but the density is mostly justified.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases. It covers raw probabilities, top_spreads_pp, compatibility fields and codes, skipped/unclassified legs, temporal alignment semantics, fee disclosure, and per-pair flags. This is unusually complete for a complex matching tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by explaining the difference between 'topic' shortcuts and explicit ticker/slug overrides, and by stating that both modes run the same token-overlap matcher. This helps an agent choose between parameter patterns.

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 and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly separates this tool from single-venue or generic arbitrage tools by emphasizing the Kalshi-Polymarket cross-venue scope, and it outlines two operating modes.

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?

Clear usage context is provided: 'topic' mode for 10 pre-mapped shortcuts versus explicit 'kalshi_event_ticker' + 'polymarket_event_slug' mode. It also cautions when the spread is meaningful ('when the bet shapes are equivalent') and warns that pre-mapped topics are frequently not tradeable. It does not explicitly name alternative sibling tools or exclusion criteria, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context beyond annotations: it is scoped to an identifier (anonymous IP, BYO key hash, account ID) and explains the listing behavior when key is omitted. No contradictions.

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

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

The description is concise and well-structured: first sentence defines core behavior, second explains usage, third covers scoping, fourth suggests pairings. Each sentence adds value, no redundancy or fluff.

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

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

Given the tool's simplicity (one optional param, no output schema, good annotations), the description is complete. It explains what the tool does, when to use it, scoping, and pairing with sibling tools. All necessary context for an agent to select and use the tool is provided.

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 one optional string parameter already described in the schema as 'Memory key to retrieve (omit to list all keys)'. The description adds usage examples and context about pairing but doesn't add new semantic information beyond what the schema provides.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys. It uses specific verbs ('Retrieve', 'list') and resource ('value previously saved', 'saved keys'). It distinguishes from sibling tools (remember, forget) by explicitly mentioning 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 explains when to use the tool: 'look up context the agent stored earlier'. It provides examples (target ticker, address, research notes) and mentions scoping and pairing with remember/forget. However, it doesn't explicitly state when not to use it or name alternatives beyond the sibling tools.

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

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

The description describes mark_read:true as flagging events read, which is a write operation. However, the annotation sets readOnlyHint=true, indicating no modifications. This contradiction means the description undermines the annotation. Score 1 required per rules.

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: purpose first, then return fields, filter options, mark_read behavior, and an alternative access note. It is slightly lengthy but concise for the amount of information. 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?

Given five optional parameters and no output schema, the description covers return fields, parameter combinations, and usage context. It lacks details on ordering or pagination, but limit is mentioned. The contradiction slightly reduces completeness, but overall it is fairly thorough.

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 covers 100% of parameters, and the description adds meaningful context: explains filter options (e.g., type 'sec_8k', since ISO timestamp), limit range, mark_read side effects, and unread_only. This goes beyond the schema's bare 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 it 'Pull fired events from your subscription feed', specifying the resource and action. It lists return fields and filtering options. However, it does not explicitly distinguish itself from sibling tools, leaving room for ambiguity.

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

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

The description explains when to use the tool (for recent alerts, polling) and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). It covers parameters like filter and mark_read but lacks explicit guidance on when not to use it or comparisons to specific 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?

The description discloses extensive behavioral details beyond annotations: fans out to multiple data sources (SEC, GDELT/GNews, USPTO), explains the GDELT→GNews fallback, mentions USPTO soft-fail, and describes the return structure. No contradictions with annotations.

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

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

The description is concise (5 sentences) and front-loaded with query examples. It could benefit from slight structuring (e.g., bullet points) but remains highly readable and informative.

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 specifies the return format (grouped changes, total count, citation URIs), covers all sources, fallback behavior, and the parallel call nature. It leaves no important gap.

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

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

Schema coverage is 100%, and the description adds meaningful context for each parameter: type limits to 'company', since explains ISO and relative formats with examples, value specifies ticker or CIK. This goes well beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, using specific examples that directly map to user queries. It explicitly distinguishes from the sibling tool entity_profile.

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

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

The description provides clear guidance on when to use this tool (temporal updates) and directs users to entity_profile for static profiles. It lacks explicit exclusion cases but covers typical usage well.

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 idempotent, non-destructive write. Description adds key details: key-value scoped by identifier, persistence for authenticated vs anonymous (24-hour retention). No contradictions.

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

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

Four sentences, front-loaded with purpose, no redundant words. Efficient structure.

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 key-value write tool with no output schema, the description covers purpose, usage, persistence, and how it integrates with siblings. Sufficient for agent 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 covers 100% of parameters with descriptions. Description adds value by providing examples of keys (subject_property, target_ticker) and values (findings, addresses), enhancing context beyond schema.

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

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

The description clearly states the tool saves data for reuse, uses the verb 'save' and resource 'data', and distinguishes from siblings recall and forget by explicitly naming them.

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 guidance with examples ('discover something worth carrying forward'), and mentions pairing with recall and forget, though no explicit 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?

Beyond the readOnly/idempotent annotations, the description reveals significant behavioral traits: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, ambiguous matches returning `figi_candidates`, and source-labelled identifiers. This gives an agent realistic expectations about partial and uncertain results.

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

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

The description is front-loaded with example intents and the primary usage rule, and it is organized by type and behavior. It is long and dense with some parenthetical asides, but nearly every sentence conveys useful guidance for a complex tool, so the length is justified.

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

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

For a tool with two entity types, no output schema, and several internal data sources, the description is remarkably complete. It covers supported inputs, output fields (`figi_candidates`, `unresolved`, source labels), ambiguity handling, and fallback behavior, leaving little unknown for an agent deciding whether and how to invoke 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?

Although schema coverage is 100%, the description adds substantial semantic value: concrete examples like 'AAPL' and '0000320193', the exact instruction to pass only the entity name, the bond-issuer caveat about trailing security-class words, and the ISIN-to-LEI resolution path. This is far more than the schema alone provides.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also enumerates concrete example phrasings and supported entity types, making the tool's role unmistakable and distinguishing it from siblings like entity_profile or compare_entities.

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

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

The description gives an explicit usage trigger: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and accepted input formats. However, it does not explicitly contrast this tool with sibling tools or state when not to use it, though the instruction to use it first strongly implies the intended context.

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

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

Annotations already provide readOnly, idempotent, and openWorld hints. The description adds value by disclosing the internal process (probes with ai_visibility_check), ranking by score, and output structure (ranked list with score, confidence, signal density). 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 three sentences, with the first sentence front-loading the core action and resource. Every sentence adds value, no fluff or redundancy.

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

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

Given the lack of an output schema, the description explains the output format (ranked list with score, confidence, signal density). It also explains the process. Minor omission: it does not mention default model behavior or the need for an API key, but schema covers that.

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 all parameters adequately. The description adds minimal extra semantic value, only noting that the first entity is treated as the 'subject'. Baseline of 3 is justified.

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 compares AI visibility across multiple entities side-by-side, using specific verb 'Compare' and resource 'AI visibility'. It distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' by detailing the internal probing and ranking process.

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

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

The description explicitly frames the tool as useful for competitive AI-marketing audits and provides a concrete motivating question. It implies when to use (multiple entities comparison) but does not explicitly state when not to use or alternatives, which is a minor gap.

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 behavioral traits beyond annotations, such as partial failure handling with timeout details (bundlephobia can take 5-30s), graceful degradation with sources_failed, and the fact that it fans out across multiple sources. 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 comprehensive but not overly verbose; it packs useful information into a few sentences. It is front-loaded with the core purpose and organized logically. A minor reduction in length could improve conciseness, but the structure is effective.

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, lack of output schema, and 100% schema coverage, the description provides a complete picture: explains return values (summary block, per-advisory detail, links, alternative versions), handles failure scenarios, and defines ecosystem boundaries. 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?

The input schema covers both parameters with descriptions, achieving 100% coverage. The description adds value by clarifying that scoped packages are accepted and that the version defaults to the latest when omitted, enhancing clarity 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 states a specific verb+resource ('scan dependency') and clearly defines it as a composite check for npm packages, covering safety, size, and popularity. It distinguishes from sibling tools by specifying ecosystem scope and the underlying external sources (deps.dev, bundlephobia).

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

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

Explicit guidance is provided: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me.' It also explicitly excludes other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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, destructiveHint=false, already indicating safety. The description adds substantial context: output includes character offsets and similarity scores, embedding model (BGE-base-en), windowing (500-char overlapping windows), and a 200K char cap with truncation flagging. 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 information-dense but logically organized: action, usage, output, pairing, technical details. Every sentence adds value, though it could be slightly more concise. Front-loaded with the key action.

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

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

Given the tool complexity (3 params, no output schema, good annotations), the description is highly complete. It explains input, output format (passages with offsets and scores), usage context, technical constraints (200K char cap, truncation flagging), and pairing with a sibling tool. No gaps for an AI agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates some schema info (text max 200K chars, query example) but does not add new parameter-specific semantics beyond what the schema already provides. The overall description helps conceptual understanding but not parameter nuances.

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,' specifying the verb (search) and resource (fetched record). It distinguishes from siblings by emphasizing it operates on already-fetched text and mentions pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages with offsets). It also provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context such as the account requirement, delivery channel behaviors (webhook auto-disable after 10 failures), and per-type parameter hints. 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 fairly long but well-structured with clear paragraphs for types and delivery channels. It front-loads the primary purpose. Minor redundancy in delivery descriptions could be trimmed.

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

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

Given seven sibling tools, no output schema, and complex nested objects, the description covers all key aspects: account requirement, type options, delivery channels, constraints. It lacks error handling or rate limit details but is sufficiently complete for subscription creation.

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. However, the description significantly expands parameter meaning with type-specific examples (sec_8k items codes, polymarket_edge topic, fred_series series_id) and delivery constraints (phone verification, webhook HMAC signing). This exceeds the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and types.

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 specifies that a Pipeworx OAuth account is required and that anonymous/BYO cannot persist subscriptions. It details delivery channel constraints (phone verification, 10/day SMS cap) but does not explicitly state when to not use this tool versus alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds detail about output structure (category-bucketed questions with exact tool + argument shape) and how calling with or without argument changes the result. No contradictions.

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

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

Description is detailed but well-structured, starting with example queries that trigger the tool, then describing behavior and usage. Could be slightly more concise, but earns its length.

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

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

For a simple discovery tool with no output schema, the description explains return shape and purpose completely. Covers triggers, output structure, and usage scenarios.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by listing example focus areas (finance, pharma, etc.) and explaining the behavior when omitted vs. specified, going beyond the schema description.

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

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

The description clearly states the tool returns category-bucketed example questions for a newly connected agent, acting as the onboarding entry point. It specifies the verb 'suggest_questions' and distinguishes it from siblings like 'ask_pipeworx' and 'discover_tools'.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the optional topic parameter vs. calling with no arguments. Provides clear context for usage.

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

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

The description reveals that the row is deactivated (not deleted) and historical events remain, adding value beyond annotations. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Three concise sentences with no wasted words, front-loaded with the purpose. Every sentence adds necessary information.

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

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

For a simple tool with one parameter and no output schema, the description covers mutation behavior, ownership, and side effects sufficiently.

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 that the id is returned by subscribe, providing helpful context beyond the schema's 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 'Cancel a subscription by id', using specific verb+resource. It distinguishes from sibling tools like subscribe and list_subscriptions.

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?

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), providing clear context for when to use. No alternative tool is named, but the guidance is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses two execution routes, the full verdict set, and crucially explains that could_not_verify means the check did not happen and carries verification_error, warning it must not be treated as evidence. It also clarifies the meaning of unsupported. This is rich, actionable behavioral disclosure with no contradiction to annotations.

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

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

The description is long but front-loaded with trigger examples and core purpose, then flows into pipeline details, verdicts, and a critical caveat. The example list is slightly redundant and the ending 'Replaces 4–6 sequential calls' is more promotional than necessary, yet overall the structure is logical and every section serves a 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?

With no output schema, the description must convey return values and error semantics, and it does thoroughly: verdict vocabulary, actual value with citation, reasoning, plus the two failure modes (could_not_verify and unsupported). For a tool of this complexity, the description is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with detailed descriptions for both claim and tolerance_pct. The description adds context about exact percent-delta math and tolerance being implied by wording, but it does not directly elaborate parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with specific example query forms. It distinguishes itself from sibling tools by laying out two concrete pipelines (SEC EDGAR/XBRL for company-financial claims and a grounded pipeline for everything else) and by noting it replaces 4–6 sequential calls. This gives a specific verb+resource and clear scope that separates it from generic ask/research tools.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a direct trigger condition. It also segments claim types to clarify which internal path applies. However, it does not explicitly name sibling tools as alternatives or provide exclusions, so it falls short of a 5.

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