Data Seattle

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

The description fully aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) and adds behavioral details: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also clarifies cost implications for Anthropic and that the default model is free. 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 two sentences, front-loaded with the core purpose, then provides key details (default model, optional key, return structure). Every sentence is necessary; 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 tool's complexity (4 parameters, no output schema), the description covers all necessary aspects: input (entity, models, apiKey, context), behavior (probing, scoring), and output (per-model fields + combined). The lack of output schema is compensated by the clear return structure in the description.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond the schema. It explains the default model, the purpose of `_apiKey` (BYO key, direct billing), and the `context` parameter ('helps disambiguate common names'). This adds significant value for correct parameter usage.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe), resource (LLMs), and output (visibility score). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on probing models rather than scanning competitor presence.

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

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

The description provides clear context: 'Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic (BYO key — you pay Anthropic directly for those calls).' It states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use it or list alternatives, but the context is sufficient for typical use.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description only needs to add behavioral context. It does this by explaining that the tool routes the question, fills arguments, and returns structured answers with stable pipeworx:// citation URIs, plus the caveat that the grounded variant is preferable when hallucination is unacceptable.

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 front-loaded with the key preference and purpose, followed by examples and routing guidance. The triage sentence about ask_pipeworx_grounded and deep_research is slightly run-on, but every part contributes useful decision-making information.

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

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

Given a single free-text parameter, no output schema, and annotations that already cover side effects, the description provides enough context: what categories of questions it handles, what it returns, and when to route to alternatives. Minor omissions like latency or output size limits are not essential for safe 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%, with the single question parameter thoroughly documented including aliases. The description reinforces natural-language usage and provides examples, but it does not add new parameter-level information beyond what the schema already specifies.

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 routes questions to one of 5,798 tools across verified sources and returns structured answers with citations. It clearly differentiates itself from web search and from the siblings ask_pipeworx_grounded and deep_research by naming when those should be used instead.

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

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

It explicitly says to prefer this tool over web search for factual/current data questions, lists trigger phrases like 'what is', 'look up', 'find', and gives concrete examples. It also names exclusions: use ask_pipeworx_grounded when ground truth is essential and deep_research for broad/multi-part questions.

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

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

Beyond the annotations, the description adds crucial behavioral context: it is a live experimental edge, candidate improvements may be active at any time, no candidate is currently active, and it has no fallback because it is a fully functioning router. This tells the agent exactly what kind of behavior to expect and that results feed into merge decisions.

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

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

The description is dense and well front-loaded, but it is slightly redundant: 'currently matches ask_pipeworx exactly' restates the no-active-candidate fact, and 'use it exactly like ask_pipeworx' echoes the earlier 'identical universal router' statement. Still, every sentence serves a purpose around identity, current state, and usage guidance.

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

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

The description is complete enough for invocation given the schema and annotations: it covers the tool's experimental nature, current parity with ask_pipeworx, and lack of fallback. It relies on the reader knowing ask_pipeworx for exact response-shape details, but it explicitly states the response shape is identical, which is sufficient for routing purposes.

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 the question parameter clearly described and all aliases listed. The description does not add parameter-level detail, but it does not need to because the schema already covers the single meaningful parameter and its five aliases.

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

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

The description explicitly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools and response shape, and clearly distinguishes it from the stable ask_pipeworx by its experimental routing candidates. The verb-resource relationship is clear: this is a full working router meant to be used like ask_pipeworx, not a stub or fallback.

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

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

It explicitly tells the agent when to use it: 'when you want the newest routing,' and names the stable ask_pipeworx as the comparison baseline and implied default. It also clarifies the current state (no active candidate, matches ask_pipeworx exactly), which is essential for deciding whether this tool adds value over the stable version.

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

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

The annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial operational context beyond that: it routes through thousands of tools, returns evidence as a verbatim quote, and refuses with specific refusal_reason values rather than fabricating an answer. It also discloses the extra LLM call cost, which is important behavioral information.

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 well-structured: purpose first, behavior second, usage and cost last. Every sentence contributes discriminating information, and the detailed return/refusal shape is justified because there is no output schema to carry that 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?

This is a complex routed tool with no output schema, yet the description covers purpose, routing behavior, return shape, refusal reasons, when to use, when to avoid, and cost. The only omitted details, such as confidence semantics, are minor and the description is otherwise complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage and already documents the question parameter and all aliases. The description adds only a light reinforcement that the input is a natural-language question, but it does not need to explain parameters further because the schema carries that burden.

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

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

The description clearly states what the tool does: it is a hallucination-resistant answer mode for high-stakes reads that extracts an answer only from the tool result. It distinguishes itself from ask_pipeworx by adding grounded extraction and explicit refusal behavior, and it is clearly differentiated from siblings such as ask_pipeworx and ask_pipeworx_beta.

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

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

The description gives explicit when-to-use guidance: use it whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also provides an explicit alternative rule: prefer ask_pipeworx for casual lookups. This makes tool selection unambiguous.

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

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

The description goes far beyond the annotations, detailing the fan-out process, resolver contract, parent event extraction, news fallback logic, safety short-circuits for low-confidence and closed markets, and resolution-rule risk. This rich behavioral context helps the agent understand the tool's internal behavior and edge cases, fully compensating for any lack of annotation detail.

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

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

The description is very long and dense, with multiple sections. While well-structured and front-loaded with the core purpose, it could be more concise. Some information (e.g., fan-out examples) is detailed but adds length. For a complex tool, this verbosity is somewhat justified, but it could be trimmed without losing essential guidance.

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

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

Given the tool's complexity (3 parameters, no output schema, many behavioral nuances), the description covers all necessary aspects: inputs, process, outputs, edge cases, safety, resolution risk, and how to interpret results. It even explains response shapes and resolver contracts. The description is thorough enough for an agent to use the tool correctly and safely.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the 'market' parameter accepts slug, URL, or question text; the 'depth' parameter defaults to 'thorough'; and the 'include_raw' parameter's effect on response size. These clarifications go beyond the schema's brief descriptions, justifying 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 that the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). The specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool ('Use for ...'). It provides guidance on interpreting results (inspect market_match_confidence, check cancellation_rule) and warns about low-confidence matches, closed markets, wide spreads, and resolution-rule risk. However, it does not explicitly mention when not to use it or alternative tools for simpler queries, so it loses a point.

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 true. The description adds substantial behavioral context: explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/ClinicalTrials for drugs), handles off-calendar fiscal years, mentions results sorted by primary metric, and includes pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with common query patterns and is information-dense. Every sentence adds value, covering usage, data sources, return format, and efficiency claim. It could be slightly streamlined (e.g., removing some examples), but overall it's well-structured and not overly verbose 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?

No output schema exists, so the description must explain return format. It does so clearly: 'paired data + pipeworx:// citation URIs per entity.' It covers both entity types, mentions sorting behavior, and implies comparison results. For a tool replacing many sequential lookups, this is rich context.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning: for 'type' it specifies what data each enum value pulls; for 'values' it provides concrete examples (tickers for company, drug names for drug) and enforces min/max items. This goes beyond schema to clarify expected input formats.

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

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

The description begins with concrete user query examples, then states it performs side-by-side comparison of 2–5 companies or drugs. It distinguishes from siblings by explicitly preferring this tool over sequential single-entity lookups, noting it replaces 8–15 calls. The purpose is unmistakably clear.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear guidance on when to use this tool. Example queries like 'which is bigger / better / larger' and 'head to head' further indicate appropriate use cases. No explicit exclusion is needed given the strong preference and clarity.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond these by disclosing account/payment requirements, latency expectations (15-60s, thorough up to ~90s), the gap-recovery and contradiction scans, the guarantee that gaps are 'never invented', and the detail that citations are always fetchable. No contradiction with annotations.

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

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

The description is dense but well-organized: account requirement, primary capability, when to use, output format, and depth-specific behavior. It front-loads the most critical gating information (account required, alternative if not signed in). It is long, but most sentences carry distinct value; a slight trim of repeated 'citation' details would improve it.

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

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

There is no output schema, yet the description fully specifies the return value: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop, and citation_uri. It also covers latency, account tiers, and alternatives. For a complex tool with only two parameters, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: depth:'thorough' requires a paid plan, latency by depth, and what each hop does in practical terms. The question parameter is also contextualized as 'broad/multi-part is fine'. This pushes 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 uses a specific verb ('research') and resource ('Pipeworx's 1517 STRUCTURED data sources') and clearly distinguishes this tool from open-web search ('this is NOT open-web search') and from ask_pipeworx. It also explains the mechanism (decomposition, parallel routing to tools) and the deliverable (findings packet with citations and gaps).

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 this tool: 'Best for broad/multi-part questions over structured data'. It also names the alternative for single lookups ('For a single lookup use ask_pipeworx instead') and includes an account-based routing rule ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). This is strong, actionable guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: returns top-N most relevant tools with full input schemas and curated examples, and each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations, though annotations cover safety and idempotency well.

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

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

The description is a single paragraph of three sentences, front-loaded with the primary verb. Every sentence adds value: purpose, when to use, what returns. No waste 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 no output schema, the description fully explains the return value: top-N relevant tools with names, descriptions, input schemas with examples, ready to call. It also covers usage guidance and examples. All relevant context 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 each parameter described. The description adds examples and explains that multiple aliases (task, q, description, search) are accepted for the query parameter, enhancing usability. While schema handles basics, description provides context and examples, earning 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 uses specific verbs (browse, search, look up, discover) and clearly states the tool's purpose: 'find tools by describing the data or task.' It distinguishes from siblings by being the only tool discovery tool, listing many data domains and explicitly advising to call it 'FIRST' when many tools are available.

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

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

The description explicitly tells when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists specific use cases (SEC filings, financials, etc.) and implies when not to use (when you already know the tool). This provides 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses fan-out behavior, source failure handling ('soft-fails until reactivated'), the meaning of empty sections ('real "no data", not a bug'), and special cases like private companies returning resolved:false. It also lists sources_used/sources_failed, giving the agent a clear model of what happens during 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 long but information-dense and well-organized, with user-intent examples up front followed by source and return details. Some example phrasings are redundant, but they serve an intent-matching purpose and do not obscure the core guidance.

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

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

For a complex tool with no output schema, the description is remarkably complete: it names every source, every major return field, failure modes, private-company handling, and input variations. An agent has everything needed to invoke it correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples and clarifies that 'type' accepts 'company' or 'ticker' interchangeably and that value can be a ticker, CIK, or name, but most of this is already present in the schema descriptions.

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

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

The description states a very specific function: building a holistic, cross-source profile of a US public company in one parallel call. It includes concrete trigger examples and enumerates the exact data sources and returned fields, making it clearly distinct from generic research or entity-resolution siblings.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a direct when-to-use instruction. It also explains accepted input forms and the private-company fallback behavior, leaving no ambiguity about when this tool is the right choice.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds minor context about cleaning sensitive data but doesn't elaborate on irreversibility or error conditions.

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, no fluff, purpose first then usage guidance. Extremely concise and well-structured.

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 (1 param, no output schema, annotations present), the description covers purpose, usage context, and pairing with siblings completely.

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 a single parameter 'key' described as 'Memory key to delete'. Description does not add extra semantics beyond schema.

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

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

The description clearly states the action (Delete), resource (memory), and method (by key). It distinguishes from siblings like remember and recall.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and suggests pairing with remember and recall. No explicit when-not-to-use, but 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the internal steps (fetches page, extracts title/description/links, emits markdown) and the output location (site-root/llms.txt). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the main action. While it includes valuable details (use cases, output format), it could be slightly more concise. Overall, every sentence earns its place.

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

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

Given the tool has only two parameters, no output schema, and comprehensive annotations, the description fully covers purpose, process, output format, and use cases. No significant gaps remain 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?

Both parameters are documented in the schema with descriptions. The tool description reinforces the url purpose and adds default and max values for max_links (default 25, max 50), which 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 function: generate a production-ready llms.txt file for any URL. It specifies the output format (standard llms.txt markdown) and lists concrete use cases (getting a client's site indexed, drafting for own project, auditing competitor). This distinguishes it from siblings like ai_visibility_check or deep_research.

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

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

The description provides usage context via 'Useful for:' but does not explicitly state when not to use the tool or compare it to alternatives. However, since no sibling tool performs the same function, the implicit guidance is sufficient for decision-making.

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 non-destructive hints. Description adds specific return fields (id, type, etc.), which enriches behavioral understanding 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?

Two efficient sentences, no wasted words. Front-loaded with action and return fields.

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

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

For a simple list operation with well-annotated structure, the description sufficiently covers purpose, return fields, and usage. No output schema, but return fields are explicitly listed.

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 includes a description for 'include_inactive'. Description does not add additional parameter semantics beyond what schema provides, hence a baseline score 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 verb 'List' and the resource 'the caller's active subscriptions'. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by specifying retrieval and listing of existing 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?

Explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. No explicit exclusions, but 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?

The description discloses non-obvious behaviors beyond annotations: rate limiting ('Rate-limited to 5 per identifier per day'), free usage, claim_token behavior ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and the team's daily digest reading. These details provide practical expectations for the agent, especially since annotations give no safety hints.

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 appropriately sized for the tool's complexity; every sentence adds relevant information. It is front-loaded with the purpose, followed by usage cases, exclusions, token flow, and operational details. No redundant content is present.

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

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

The description covers all necessary context: when to use, boundaries, token handling, rate limits, and even motivational context ('signal directly affects roadmap'). It is complete enough for an agent to confidently invoke the tool without external documentation, even without an output schema.

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

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

The input schema already provides descriptions for all parameters (100% coverage), so the baseline is 3. The description adds value by explaining how to use the claim_token parameter in the context of a previous filing, and it enriches the message parameter by instructing to avoid pasting the user's prompt. It also clarifies that context is optional structured context, which is helpful.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings by emphasizing it is ONLY for tools served by this Pipeworx connection, and it enumerates the feedback categories (bug, feature/data_gap, praise). This is a specific verb+resource that differentiates it from other MCP server feedback channels.

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 provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use rule: if the tool came from a different MCP server, file it there instead. Additional guidance about identifying Pipeworx tools and avoiding pasting end-user prompts completes the usage picture.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), structure (pack, tool, count), and caching (5min-1h). This exceeds 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?

Description is concise (three sentences plus bullet list) and well-structured. Every sentence adds value—use cases, data provenance, caching behavior. 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 (1 optional param, no output schema, rich annotations), the description is complete. It covers data origin, privacy, caching, and practical use cases. No gaps 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?

Only one optional parameter 'window' with enums. Schema coverage is 100% (description in schema clarifies each window). Description adds minimal extra context ('shorter windows surface what's hot'). Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states the tool returns top tools, packs, and call volume over recent windows. The verb 'returns' and specific resource ('trending data on Pipeworx') make the purpose unambiguous. It also lists three concrete use cases, distinguishing it from sibling tools like 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?

Description explicitly provides three use cases (discovering hot data, confirming canonical choice, aligning use case) and mentions caching behavior. It lacks explicit when-not-to-use or alternatives, but the use cases sufficiently guide appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: internal monotonicity checks, partition sum checks, semantic anchor with Jaccard similarity, partition filter for placeholders, fill check against live order book depth, and output structure. No contradictions.

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

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

The description is relatively long but well-structured. It fronts the main purpose, then details each mode, then covers secondary behaviors like fill check. Every sentence adds value, though some details like the fill check and custom sizing could be slightly condensed. Still, complexity justifies length.

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

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

Despite no output schema, the description thoroughly covers return values (opportunities array, partition_check with fields) and behavior. It explains the fill check, semantic anchor, partition filter, and when signals are false. For a complex arbitrage tool, this is complete.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant meaning: for event, it explains walking child markets and checks; for topic, it explains searching related events and flattening markets. It also mentions accepted formats (full Polymarket URLs for event).

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending scan), event (specific market), and topic (cross-event scan). This is specific and differentiates from all sibling tools, none of which focus on arbitrage.

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

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

The description explicitly tells when to use each mode: no args for a trending scan, event for a specific market (recommended), and topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp <= 0) and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description goes beyond this by detailing the three response segments, edge calculations (edge_pp_net, kelly_fraction), liquidity and spread filters, caching behavior, and diagnostic fields. No contradictions with annotations; the description adds significant behavioral context.

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

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

The description is verbose but efficiently packed with information. It front-loads the core purpose and then dives into segments, edge metrics, and knobs. Every sentence adds value. Minor improvement could be using bullet points or sections, but the structure is logical and clear for an AI agent.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It covers output structure (by_segment, fed_candidates, diagnostics), explains why segments may be empty (filter skips, stale data), and details caching (Cached 1h at KV level). Agents have all necessary context to use the tool effectively.

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

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

Schema coverage is 100% (all 9 parameters have descriptions). The description adds extra context for several parameters, such as slippage_pp (explaining zero fees but bid/ask impact), min_liquidity (walking the book), and min_partition_leg_kelly (why min_kelly doesn't filter partition arbs). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific resource (Polymarket markets) and action (scan and return opportunities). The segmentation into model-driven, structural arbitrage, and concentrated longshots distinguishes it 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 context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies when to use (daily bet discovery) but does not explicitly state when not to use or name alternatives. However, the extensive detail on model families and edge metrics helps agents understand its domain.

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 readOnly, openWorld, idempotent, not destructive. Description adds extensive behavioral detail: response structure (tracked, expired, snapshot_dates), decay computation on absolute value, signed interpretation, daily closes not intraday, 60-day TTL, snapshot start condition. Goes well 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?

Description is dense and informative, but somewhat long. Every sentence adds value. Minor inefficiency: parenthetical about negative sign could be in parameter description. Overall well-structured and front-loaded with purpose.

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

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

No output schema exists, so description fully explains return values: tracked array with time-series, first_seen, trend, decay; expired array with lifespan; snapshot_dates. Covers caveats (TTL, daily nature, snapshot gaps). Complete for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions including defaults and ranges. Description restates defaults ('days default 14, max 30'; 'window default 1wk') but adds no new semantics beyond schema. Baseline 3 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?

Describes specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' Clearly answers 'how long has this edge existed and is it shrinking?' Distinguishes from sibling 'polymarket_edges' by focusing on persistence and decay rather than raw snapshots.

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

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

Explains when to use: to differentiate between fresh and old edges. Provides concrete example (fresh vs 3-week-old edge). Lists limits (60-day TTL, snapshot gaps). Does not explicitly state when not to use or compare directly to all siblings, but 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds context beyond annotations: describes walking the ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, verdict), and highlights risks (thin_legs, forced_directional_risk). No contradiction.

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

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

Description is long but well-structured with clear sections for single-market and basket modes, plus usage warnings. Front-loaded with key info. Could be slightly more compact but 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?

Despite no output schema, description lists all returned fields (top_of_book, vwap_fill_price, verdict, etc.) and covers both modes, parameter nuances, risks, and use cases. Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds rich meaning: explains size_usd in basket mode as 'settlement notional', default side behavior (auto from partition sum), and constraints (clamp 10–1,000,000). Goes well 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 checks realizable-vs-theoretical edge against live order-book depth, distinguishing single-market and basket modes with specific verbs like 'walks the ladder' and 'returns...'. This is highly specific and differentiates from siblings like 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?

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains consequences of not using it (theoretical overround not capturable, partial fills convert arb to directional position). No 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?

Goes far beyond the readOnlyHint/idempotentHint annotations, disclosing exactly what is computed, what is skipped, when warnings appear, how nulls are to be interpreted, that Kalshi fees are not modeled, and that returned pairs remain unverified. This is exemplary for a data tool with no output schema.

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

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

The description is long, but it is densely structured with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every section carries non-redundant operational detail. It is not crisp, yet the length is justified by the tool's complexity, lack of output schema, and need for safety disclosures.

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 there is no output schema, the description thoroughly accounts for response contents, all safety fields and codes, skipped pair semantics, temporal alignment handling, and fee caveats. An agent has enough information to call the tool correctly and interpret its results without guessing.

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 reinforces each parameter's meaning, especially the topic enum list and the override semantics of kalshi_event_ticker and polymarket_event_slug. It adds the important note that explicit fields override the topic-mapped side, which the schema alone does not state.

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?

States a specific resource and operation: computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two-mode design (topic shortcuts vs explicit ticker/slug) is clearly distinguished, and the description notes the tool differentiates real signal from non-equivalent bet shapes, setting it apart from generic sibling tools like 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?

Provides explicit guidance for both usage modes, explains when to use pre-mapped topics vs explicit event identifiers, and warns that pre-mapped topics are not automatically tradeable. It also clarifies that both modes run the same matching logic, so guidance about disclosures applies equally. Caveats like 'check the close/strike date yourself' further steer correct use.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about scoping to identifier and pairing with remember/forget, enriching 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?

Two sentences, front-loaded with the primary action, no unnecessary words. Efficient and well-structured.

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 one optional parameter, rich annotations, and no output schema, the description covers purpose, usage, scoping, and pairing with siblings. Complete for a read tool.

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

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

Schema description coverage is 100% and already explains omitting key lists all. Description restates this but adds no new meaning 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?

Description clearly states 'retrieve a value previously saved via remember, or list all saved keys', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'forget'.

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

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

Describes when to use: 'look up context the agent stored earlier' and scoping to identifier. Lacks explicit 'when not to use' or alternatives beyond mentioning siblings with different verbs.

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, idempotentHint=true, destructiveHint=false. The description adds important behavioral details: setting mark_read:true flags events as read (a non-destructive side effect), and mentions that the feed is persisted and accessible via a GET endpoint. No contradictions.

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

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

Three well-structured sentences, each adding value. Front-loaded with purpose, then details on return fields and parameters, then usage guidance. No unnecessary words.

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

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

Despite no output schema, the description sufficiently explains return fields (source, citation_uri, raw payload) and provides context on polling and alternative access. For a read-only tool with 5 optional parameters, this is complete and self-contained.

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 meaning to each parameter: type filter, limit max, since ISO timestamp, mark_read flag behavior (flags events read in same call), unread_only filter. This goes beyond the schema's basic descriptions.

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

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

The description states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes itself from siblings like list_subscriptions and recall by focusing on fired alerts and providing details on return fields (source, citation_uri, raw payload) and filtering options.

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 this tool (retrieving fired events from subscription feed) and notes that 'Polls work fine' and an alternative GET endpoint exists. It doesn't explicitly state when not to use it, but the guidance is clear and practical.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: fan-out to multiple APIs, GDELT/GNews fallback, PatentsView sunset, and return structure. No contradictions.

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

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

Description is well-structured with examples and parentheticals. Every sentence adds value. Front-loaded with purpose and use cases, then detailed behavior. 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?

Given no output schema, the description explains return structure (changes[], total_changes, citation URIs) and handles edge cases like patent API sunset. It is thorough and covers all essential behavioral aspects.

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 decent descriptions. The description adds concrete examples for 'since' (ISO, relative) and 'value' (ticker, CIK), improving usability. Baseline 3, elevated by additional guidance.

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

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

The description clearly states the tool provides a change feed for a company (SEC filings, news, patents) in a given time window. It distinguishes from sibling 'entity_profile' by specifying use cases. Purpose is specific and well-defined.

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

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

The description includes example queries and explicitly says when to use 'entity_profile' instead. It explains fallback behavior for news and patent limitations. However, it doesn't exhaustively list when not to use this tool or other alternatives.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are enhanced by the description which adds behavioral details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 the core purpose. Every sentence adds value: main action, when to use, scope, persistence details, and sibling references. 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?

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description is complete. It covers purpose, usage, behavioral traits, and parameter conventions adequately for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context by providing conventions for key (e.g., 'subject_property') and value types, which adds meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and the resource 'data' with clear use cases (resolved ticker, address, preference). It distinguishes itself from siblings like recall and forget by mentioning them directly.

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 tells when to use the tool: 'when you discover something worth carrying forward.' It also mentions when not to use alternatives by pairing with recall and forget, providing clear context for choosing this tool over 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses substantial behavioral traits: multi-source identity assembly (EDGAR, GLEIF, OpenFIGI), graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-match behavior returning `figi_candidates` rather than asserting, explicit `unresolved` section for failed identifiers, and internal cascading across lookup endpoints. It also reveals the ISIN-to-LEI mapping behavior for non-US issuers. No contradiction with annotations exists.

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 user intents and the core purpose, followed by organized SUPPORTED TYPES sections. It is dense and somewhat run-on, with long parentheticals, but every section conveys essential information for a tool of this complexity. It loses a point for verbosity and lack of paragraph breaks, but it earns its length given the two entity types and multiple edge 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?

There is no output schema, so the description carries the full burden of explaining return behavior. It covers what identifiers are returned, how sources are labeled, how ambiguity is handled (`figi_candidates`), how failures are reported (`unresolved`), and the graceful degradation fallback. It also covers complete input semantics. Given the tool's complexity and absence of an output schema, the description is remarkably complete.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For `type`, it explains the full behavior of 'company' (CIK, ticker, LEI with ownership, FIGI for non-equities, unresolved labeling) and 'drug' (RxCUI, ingredient, brand, citation). For `value`, it provides examples, accepted identifier formats, and a critical pitfall about passing the issuer name only for bonds. This far exceeds the baseline expected from high schema coverage.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also opens with concrete user-phrase examples ('What's the ticker for…', 'find the CIK for…') and explicitly distinguishes itself by instructing 'Use FIRST whenever you have a name but need an ID,' separating it from siblings like entity_profile and 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 clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details acceptable input formats (ticker, CIK, ISIN, company name; brand or generic drug name) and warns against passing full noun phrases for bond lookups. It does not name alternative tools explicitly or state when not to use it, but the 'FIRST' directive and input constraints provide sufficient 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density – valuable context beyond annotations.

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

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

Two sentences, front-loaded with core purpose. Every sentence adds value: first defines action, second explains process and use case. 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?

Given moderate complexity (comparing multiple entities, ranking), the combination of rich annotations, full schema, and clear description fully covers purpose, usage, behavior, and expected output.

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 parameter descriptions. The description adds narrative context (e.g., 'First entry treated as subject') but does not significantly enhance semantics beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb, resource, and scope. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides clear usage context ('competitive AI-marketing audits') and an example question. It implies when to use this over single-entity probes, though explicit when-not-to-use is missing.

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

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

The annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds significant behavioral context beyond annotations: it explains partial failures ('sources_failed will list it if it times out'), timing expectations ('bundlephobia's first measurement on a new version can take 5-30s'), and the composition of the response (summary block, per-advisory detail, links, alternative versions). 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 well-structured, starting with a concise summary of the composite check and usage notes. It front-loads the main purpose and usage. However, the list of returned fields (is_latest, license, etc.) is somewhat verbose and could be delegated to an output schema if one existed. Overall, the description earns its space but could be slightly 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 the tool's complexity (two external services, partial failures, rate/timing considerations) and the lack of an output schema, the description covers all essential aspects: it describes the return values, explains graceful degradation, and notes the potential delay for new versions. It is complete for an agent to understand what the tool does and what to expect.

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

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

Input schema coverage is 100%, providing baseline 3. The description adds meaning beyond schema: it explains that the package parameter accepts scoped packages like '@types/node', and that the version parameter defaults to the latest version when omitted. This enhances understanding, though the schema already provides clear 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 performs a composite check across deps.dev and bundlephobia for npm packages. It uses the verb 'scan' and specifies the resource ('npm package'), making the purpose unambiguous. The description distinguishes the tool from siblings by noting that other ecosystems are handled by a different tool.

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

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

The description explicitly states when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies the ecosystem limitation ('NPM ecosystem only in v1') and directs users to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This provides clear when-to-use and when-not-to-use guidance.

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

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

Adds value beyond annotations by disclosing the embedding model (BGE-base-en), window size (500-char overlapping), token cap (200K chars with truncation and flagging), and similarity metric (cosine). 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?

Pithy and well-structured. First sentence states core action. Subsequent sentences add context, use cases, and technical details. Every sentence contributes meaningfully.

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

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

Despite lacking an output schema, the description explains return format (passages with offsets and similarity scores). For a tool with 3 parameters and comprehensive annotations, this is fully sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add per-parameter details beyond schema, but provides useful context for the 'query' parameter with example queries. No extra semantics for 'text' or 'limit'.

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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and specifies output (passages with offsets and scores). Distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing strategy.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Mentions pairing with ask_pipeworx_grounded for grounding. While no explicit when-not-to-use, the guidance is clear and actionable.

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, open-world, and idempotent behavior. The description adds value by specifying the return format (dataset names, descriptions, resource ids) and the intended follow-up tool. This goes 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 two sentences: first states the action and resource, second states the return type and usage. Every sentence provides unique information, no fluff, and the key 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?

With no output schema, the description adequately explains return values (names, descriptions, resource ids). It also mentions the optional API key indirectly via schema. It could mention pagination behavior or offset parameter, but the offset parameter itself hints at that. Overall, it's sufficient for a search 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 baseline is 3. The description does not add new parameter details beyond the schema, but it provides context for how parameters like 'query' and 'limit' are used in the search. The examples in schema also help, but the description itself is not essential for parameter understanding.

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

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

The description clearly states the verb 'Search', the resource 'Seattle open-data catalogue (data.seattle.gov)', and what is returned. It distinguishes itself from the sibling 'seattle_query' by noting the output is resource ids for use with that tool.

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

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

The description provides clear context by stating it returns Socrata resource ids to use with 'seattle_query', implying a workflow. However, it does not explicitly mention when to avoid this tool or provide alternatives for similar tasks like browsing recent datasets (seattle_recent).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description complements this by explaining the tool runs raw SoQL queries, which is consistent. It adds context about the data source and query syntax but doesn't detail response format or error behavior, which is acceptable given the annotations.

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

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

The description is extremely concise, consisting of two sentences that convey the tool's purpose, functionality, and guidance on alternatives. No redundant 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 the tool's complexity (raw SoQL with 8 params) and no output schema, the description covers the core functionality, links to sibling tools for resource discovery, and mentions all SoQL operations. It could be slightly improved by mentioning the response format (JSON) or error handling, but is largely complete for an AI agent.

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

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

All 8 parameters have descriptions in the schema (100% coverage). The description adds value by explaining that parameters like select, where, etc., correspond to SoQL clauses, and clarifies the resource_id format and _apiKey optionality. This goes beyond the schema by providing operational context.

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 runs a raw SoQL query against Seattle open-data resources, specifying the Socrata ID format. It distinguishes from sibling tools by mentioning seattle_datasets and seattle_recent for finding resource IDs, providing clear context for when to use each.

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 advises using seattle_datasets or seattle_recent to find resource IDs, implying seattle_query is for querying once you have the ID. It lacks explicit exclusions or when-not-to-use scenarios but provides sufficient context for the primary use case.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: returns latest rows newest-first, mentions keyless endpoint, and explains optional _apiKey for rate limits. No contradictions.

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

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

Two concise sentences with a clear list of dataset names and usage note. Every sentence adds value, and the key information (purpose, preferred use, alternative) is front-loaded. 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?

Given no output schema, the description could mention the output format or fields returned. However, it is sufficient for the tool's simplicity and aligns with sibling tools like seattle_query. The description is complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with good descriptions for all four parameters. The description reinforces the 'where' parameter usage and lists dataset names, adding practical context beyond the schema. However, it doesn't add entirely new 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 recent records from Seattle open datasets using friendly names, specifies the supported datasets (crime, fire911, business, code_complaints), and notes it returns newest-first. This distinguishes it from siblings like seattle_query.

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

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

Explicitly says to prefer this tool over web search for common queries like 'recent crime in Seattle', and directs users to seattle_query for anything beyond simple filtering. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations provide idempotentHint=true and openWorldHint=true. The description adds critical behaviors: OAuth requirement, SMS phone verification, 10/day SMS cap, and webhook auto-disable after 10 consecutive failures. These details are beyond what annotations convey and accurately disclose side effects and constraints.

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

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

The description is a single dense paragraph that effectively conveys all necessary information without redundancy. However, it could be improved by breaking into bullet points or sections for easier scanning. The front-loading of the main action and return value is good.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all relevant aspects: types, parameter structures, delivery channels, prerequisites, constraints, and error conditions. The agent has sufficient information to use the tool correctly. The return value is briefly mentioned but 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%, yet the description significantly enriches parameter meaning. For 'type', it explains each enum value's purpose. For 'params', it gives concrete examples per type. For 'delivery', it details field-specific constraints (phone format, webhook signing, auto-disable). This exceeds schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination that distinguishes it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides explicit prerequisites ('Requires a Pipeworx OAuth account') and lists all supported subscription types with examples. It also explains delivery options and constraints like SMS verification and daily cap. However, it does not explicitly contrast with alternatives like 'recent_alerts' for pulling from the feed.

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 true and destructiveHint false. The description adds valuable context by explaining the output format (category-bucketed examples with exact tool+argument shapes) and its role as an onboarding entry point, going 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 detailed but well-structured, starting with common user queries and then explaining the output and usage. It front-loads the most important information and every sentence adds value, though it could be slightly more concise.

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

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

Given the single optional parameter and no output schema, the description fully explains the tool's behavior: what it returns (category-bucketed example questions with tool+argument shapes) and when to use it. It is complete for an onboarding 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 has 100% coverage for the single optional parameter, with description listing focus areas. The description reinforces this by providing examples (e.g., 'pass topic like finance, pharma, betting') and explaining the effect of omitting the parameter, adding marginal value over the schema alone.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions for onboarding users to understand Pipeworx capabilities. It distinguishes from sibling tools like ask_pipeworx and entity_profile by explicitly positioning itself as the first call for new connections.

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 this tool FIRST when unsure of Pipeworx's capabilities, and provides guidance on omitting arguments for a full spread or passing a topic for focus. It also mentions learning how to call meta-tools, offering clear context for when to use this tool versus alternatives.

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

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

Annotations are already present, but the description adds valuable context: ownership enforcement, deactivation vs deletion, and that historical events remain available via recent_alerts. No contradictions.

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

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

Three sentences, each essential: purpose, ownership, and deactivation nuance. No wasted words, 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?

For a simple tool with one required parameter, no output schema, and good annotations, the description fully covers purpose, side effects, and sibling relation to recent_alerts. Complete enough.

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 repeats that the subscription is identified by id but does not add new parameter-specific details 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 verb 'cancel' and the resource 'subscription by id'. It distinguishes from sibling tools by specifying ownership enforcement and the deactivation (not deletion) behavior.

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

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

The description explicitly says ownership is enforced, so the tool is only for your own subscriptions. It does not mention alternatives or when not to use it, but the context is clear and 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 readOnly/openWorld/idempotent, so the bar is lower, but the description adds crucial behavioral nuance: the meaning of each verdict, especially that 'could_not_verify means the check did not happen... must not be shown as evidence,' and that 'unsupported' means no source exists. This goes well beyond basic safety hints and explains the tool's failure modes.

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

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

The description is fairly long but every sentence adds value—trigger phrases, pipeline routing, verdict definitions, and error-handling clarifications. It is front-loaded with usage examples and structured logically. It could be trimmed slightly (e.g., the 'Replaces 4–6 calls' sentence is somewhat promotional), but it remains efficient for a complex tool.

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

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

The description covers everything an agent needs to decide on and process a call: input type, routing rules, output structure (verdict + value + citation + reasoning), and special-case handling (could_not_verify vs. unsupported). With no output schema, this description carries the full burden of explaining return values, and it does so thoroughly.

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 practical guidance beyond the schema: it explains how 'tolerance_pct' interacts with claim wording (default implied, capped at 5) and recommends 1–2 for hallucination detection. It also provides example claim formats in the schema, but the description reinforces the intended use of the parameter.

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

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

The description opens with concrete trigger phrases ('Is it true that…', 'fact check') and explicitly states the tool's function: natural-language claim verification against authoritative sources. It clearly differentiates from siblings by explaining its dual path (SEC EDGAR/XBRL fast path for company-financial claims vs. grounded pipeline for anything else), making its purpose unmistakable.

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

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

Provides an explicit usage condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when the fast path vs. grounded pipeline applies. However, it does not name specific alternative tools or explicit 'when not to use' scenarios, so it stops 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.