Ipqualityscore

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing the probing process (per-model scores, raw responses, combined view), cost implications (free Workers AI, BYO Anthropic), and return structure.

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 front-load purpose and return format. Every sentence adds value: use case, default model, optional Anthropic, return details. No redundancy.

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

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

With 4 parameters, no output schema, and moderate complexity, the description fully explains the return structure (score, confidence, signals, raw_response, combined view) and usage scenarios. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description enriches parameters with examples ('Pipeworx', 'sk-ant-...'), clarifies optionality (_apiKey only for anthropic), and explains context's purpose (disambiguate). Exceeds baseline.

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

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

The description clearly states it probes LLMs to score visibility (0-100) for a brand/product/topic. It distinguishes from siblings like ask_pipeworx or deep_research by focusing on AI-marketing audits and brand checks.

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 (pre-launch brand checks, competitive monitoring) and provides model selection guidance (default Workers AI, Anthropic with _apiKey). It lacks explicit exclusions or comparison to siblings but overall provides 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 already cover readOnly, idempotent, and openWorld safety hints. The description adds valuable behavioral context: routing across 5,743 tools, filling arguments, returning stable pipeworx:// citation URIs, making one fast call, and working on every tier. This goes beyond the annotations without contradicting them.

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

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

The description is long, but it is well-structured with a front-loaded preference call, a capability statement, trigger phrases, examples, and explicit alternative routing. Every section earns its place for a complex router tool, though a slightly tighter edit 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?

Given the broad routing nature, a single free-text parameter, and no output schema, the description covers the necessary ground: what to ask, when to use it, when to use alternatives, what to expect back (structured answer with citation URIs), performance ('one fast call'), and tier accessibility. Nothing critical is missing.

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

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

Schema coverage is 100% and the question parameter is already described with aliases. The description enriches this by explaining what kinds of natural-language inputs are appropriate ('what is', 'look up', 'get the latest', etc.) and providing realistic examples, helping the agent formulate effective queries.

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 defines ask_pipeworx as a routing tool that answers factual questions using authoritative structured data with citations, and enumerates specific domains (SEC, FDA, FRED/BLS, patents, weather, clinical trials, etc.). It differentiates itself from siblings by claiming the 'default entry point' role and explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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

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

The description gives direct usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It lists trigger phrasings ('what is', 'look up', 'find', etc.), provides concrete examples, and clearly states when to step up to ask_pipeworx_grounded or deep_research. It even handles the breaking-news edge 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?

Beyond the readOnly/idempotent annotations, the description discloses that candidate routing improvements are enabled live when under test, that no candidate is currently active, and that this is a full working router with no fallback. This is valuable dynamic behavioral context an agent needs before invoking the tool.

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

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

The description is moderately detailed but efficient, front-loading the beta/aspect and same-arguments statement before explaining live status and usage. Minor redundancy exists in 'Falls back to nothing' plus 'this IS a full working router,' but it still earns its place.

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

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

For a beta router with dynamic candidate behavior, the description covers current state, equivalence to the stable tool, usage, and response-shape consistency. It is nearly complete, though it could more explicitly advise against use when stable behavior is strictly required.

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 parameters are already fully documented as aliases for the question. The description adds only that this tool takes the same arguments as ask_pipeworx, which is mildly useful but does not introduce meaning beyond the schema.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It differentiates it from the stable sibling by calling out candidate routing improvements and the experimental edge.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies that results are compared against the stable router. It does not explicitly state when not to use it, but the 'experimental edge' framing and current no-candidate status provide enough context.

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

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

Beyond the readOnly and idempotent annotations, the description reveals refusal behavior with enumerated refusal reasons, evidence extraction via verbatim quotes, and the extra LLM call cost. This gives the agent a clear model of failure modes and output guarantees.

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 perfectly front-loaded: purpose, mechanism, return shapes, usage guidance, and cost tradeoff appear in logical order. Every sentence carries essential information with no filler.

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

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

There is no output schema, so the description compensates by fully specifying both the success response fields and the explicit refusal response variants. Together with annotations and input schema, an agent has everything needed to select, invoke, and interpret this tool.

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

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

Schema coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds no parameter-specific semantics beyond the generic 'fills arguments' phrase, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb and resource. It distinguishes itself from ask_pipeworx by noting identical routing but stricter extraction, and by defining the success and refusal return contracts.

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

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

Provides explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on in financial, legal, medical, or public-statement contexts. It also explicitly recommends preferring ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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

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

The description extensively details behavioral traits beyond annotations: low-confidence resolution short-circuit, closed market handling, wide spread warnings, resolution-rule risk, and blocking paths. Annotations only indicate readOnly, idempotent, openWorld, so the description adds significant value.

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

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

The description is front-loaded with a clear first sentence but becomes very lengthy with multiple detailed sections (classifiers, fan-out examples, response shapes). While all content is relevant, conciseness is sacrificed for completeness.

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

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

Given the tool's complexity and no output schema, the description covers all necessary aspects: input options, resolution process, edge cases (closed markets, low confidence), result structure (market, analysis, evidence), and safety warnings. It is exceptionally thorough.

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

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

Schema description coverage is 100%, with each parameter already well-described. The description reiterates some of this (e.g., market input formats) but does not add substantial new semantic meaning beyond the 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 the tool researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text). It distinguishes itself from siblings by detailing a comprehensive research pipeline, making its unique purpose unmistakable.

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

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

The description explicitly says 'Use for' followed by example queries like 'should I bet on X', providing clear usage context. However, it does not explicitly state when not to use or mention alternatives, so it misses the top tier's exhaustive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful unannotated context by revealing that the tool depends on the external IPQualityScore API and requires a user-supplied key. It does not mention rate limits or third-party data handling, but the authentication dependency is the key behavioral disclosure beyond annotations.

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

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

The description is three sentences with a front-loaded purpose, a compact usage example, and a necessary credential requirement. Every sentence earns its place, and there is no filler or repetition of annotation data.

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 correctly explains the return value in prose (fraud score plus deliverability, SMTP, and DNS signals) and covers the required external API key. It does not describe exact response shape or error conditions, but for a two-parameter, read-only tool this is still adequately 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%: both email and _apiKey are fully documented in the schema, including where to obtain the IPQualityScore key. The description restates the example and key requirement but adds no new semantic meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb-plus-resource statement ('Email fraud & deliverability check') and enumerates concrete behaviors: validates the address, detects disposable/temporary addresses, flags data-leak exposure, and returns a 0-100 fraud score plus SMTP/DNS validity signals. This clearly differentiates it from sibling tools like check_ip, check_phone, and check_url.

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

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

The description provides clear context for when to use the tool: whenever an email address needs fraud, deliverability, or validity assessment. It implies a natural separation from sibling resource-specific checkers, but it never explicitly states when not to use it or names alternatives, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by revealing an external API dependency and the need for a bring-your-own key, plus the specific output content (fraud score, geolocation fields). 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 compact and front-loaded: purpose first, then a concrete example, then the key requirement. Every sentence contributes useful information, and there is no redundant restating of schema 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?

The description explains the tool's purpose, input, external key requirement, and output characteristics despite lacking an output schema. An agent has enough context to call it correctly and interpret the result at a high level.

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 all three parameters are already documented in the input schema. The description reinforces the _apiKey requirement and shows an example call but does not add meaning beyond what the schema provides, so a baseline 3 is appropriate.

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

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

States a specific verb and resource: fraud detection and risk scoring for an IP address. The description answers concrete questions (proxy/VPN/Tor, bots/crawlers, abuse) and lists output fields, making it unambiguous and distinct from sibling tools like check_email or check_phone.

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?

Clearly defines the use case as IP risk assessment and provides the important prerequisite of a user-supplied IPQualityScore API key. It does not explicitly name alternatives or exclusion criteria, but the domain is clear enough for an agent to select it appropriately among siblings.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, reducing the burden on the description. The description adds substantive behavioral context beyond annotations: the external IPQualityScore API dependency, the requirement to pass a caller's own _apiKey, and the output dimensions (fraud score, line type, carrier, region, risk flags). This is valuable given there is 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?

Three dense, purposeful sentences: the first front-loads the core function and output, the second gives a concrete invocation example, and the third states the required API key. Every sentence earns its place with no filler 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?

For a tool with no output schema, the description covers purpose, key output facets, the external API key requirement, and an example call. It does not specify the exact response shape or mention rate limits/free-tier caveats, but it provides enough for an agent to select and invoke the tool correctly, especially with annotations carrying the safety profile.

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 each parameter (phone, _apiKey, country) already documented with examples and purpose. The description repeats the phone/country example but adds no new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific resource (phone) and distinct actions: validation, active-status confirmation, fraud score (0-100), and flags for VOIP/prepaid/risky numbers with line type, carrier, and region. This clearly differentiates it from sibling tools like check_email, check_ip, and check_url, which share the check_* pattern but target different resources.

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

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

The description implies 'use when you need phone number validation and fraud checking' but provides no explicit when-to-use/when-not-to-use guidance or named alternatives. It does not reference sibling tools like check_email or check_ip, so an agent must infer the appropriate selection from the resource type alone.

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, indicating a safe, side-effect-free operation. The description adds valuable behavioral context by disclosing the API key requirement (external authentication) and enumerating the returned data fields. This goes beyond the annotations but could have been richer (e.g., note that it makes an external network call, potential rate limits), but for a read-only scan the key requirement is the most critical behavioral detail.

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

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

The description is concise: two sentences and an example. The primary purpose is front-loaded, the output types are listed, and the API key requirement is stated without unnecessary detail. Every sentence earns its place, and the formatting is clean and scannable.

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

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

For a simple tool with two parameters and no output schema, the description covers the essential context: what it checks, what it returns, and the prerequisite API key. The return values are enumerated but not detailed in format (e.g., risk score range), yet for an agent to decide if this tool is suitable, the listed information is sufficient. The lack of explicit output schema is mitigated by listing the return fields, so the description is as complete as needed for this complexity level.

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 `url` and `_apiKey` adequately described in the schema. The description adds a concrete example and clarifies that the API key is user-provided (BYO) with a pointer to the free tier, but this is marginal added value. The baseline for high schema coverage is 3, and the description does not substantially enrich parameter meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it performs a URL/malware safety scan, checking for phishing, malware, and spam. It names the specific output fields (risk score, domain reputation rank, content category, DNS validity, domain age) and includes an example invocation. This distinguishes it from sibling tools like check_email, check_ip, and check_phone, which focus on other entity types.

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

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

The description implicitly communicates when to use this tool: when a URL or domain needs a safety check. It also provides a clear prerequisite: the user must supply their own IPQualityScore API key, with a note about the free tier. However, it does not explicitly contrast with sibling tools or state when not to use it, though the distinct entity type (URL vs email/IP/phone) makes the intent 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 detailed behavioral traits: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and return of paired data with citation URIs. Annotations already indicate read-only, open-world, idempotent, non-destructive; the description adds substantial 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 front-loaded with example queries, making intent clear quickly. While somewhat lengthy, each sentence adds useful information. Structure uses dashes for lists, aiding readability. Slightly verbose but effective.

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

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

With no output schema, the description mentions 'paired data + pipeworx:// citation URIs per entity' but lacks details on the structure or format of the comparison results. This could hinder an AI from correctly interpreting the output. Otherwise, the description covers key 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%, but the description adds meaning beyond enum labels: explains type='company' pulls latest 10-K financials, type='drug' pulls FAERS counts. For values, it specifies tickers/CIKs for companies and drug names, with a limit of 5. This adds value, though more detail on specific metrics could improve.

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: side-by-side comparison of 2-5 companies or drugs in one call. It includes example queries like 'Compare X and Y' and distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

The description explicitly advises to prefer this tool over sequential single-pack lookups for comparisons. It provides context for when to use (comparison questions) and implies alternatives (entity_profile for single lookups). However, it does not explicitly list exclusions.

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

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

The description goes well beyond annotations, detailing the internal behavior: question decomposition, routing to 5,743 tools in parallel, a findings packet with evidence/confidence/source/fetched_at citations, explicit gaps[] for unanswered facets, never-invented answers, contradictions[] for deeper tiers, semantic excerpting, and expected latency. No annotation contradiction is present.

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 and dense, but it is information-rich rather than padded, with the key routing advice front-loaded. Some parenthetical chains could be tightened, but each clause adds a distinct operational detail.

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

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

Despite having no output schema, the description covers auth requirements, alternative tool routing, input suitability, output shape, gap handling, citation resolvability, result reliability, and timing. For a complex research tool, 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 coverage is 100% and both parameters are already described in the schema. The description adds meaningful context on top: the 'thorough' depth requires a paid plan, what each depth tier costs in time, and which tiers include the contradictions[] scan. This is more than the schema alone provides.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1500 structured data sources in one call, with parallel decomposition and routing. It explicitly contrasts with open-web search and names ask_pipeworx for single lookups, so it is clearly distinguished from siblings.

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

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

It gives explicit when-to-use guidance: use deep_research for broad/multi-part structured-data questions, and use ask_pipeworx for a single lookup. It also provides a catch-condition: if not signed in, use ask_pipeworx instead because it works on every tier.

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

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

Discloses that returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, ready to call. Annotations already declare read-only, idempotent, non-destructive; description adds behavioral detail 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?

Front-loaded with purpose, followed by usage example and output format. Every sentence adds value; no wasted words.

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

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

Despite no output schema, description fully explains what the tool returns (top-N ready-to-call tools with schemas). Complete for a discovery tool.

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

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

Schema coverage 100%, so baseline 3. Description adds extra context: accepts multiple aliases for query, and specifies limit default (20) and max (50).

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 tools by describing data or task, listing many domains. It distinguishes itself from siblings as the only 'discover' 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance.

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

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

Annotations already declare read-only, idempotent, open-world behavior, but the description adds substantial behavioral context: parallel fan-out across multiple external sources, fallback order (GDELT→GNews), the meaning of sources_used/sources_failed, empty sections as real 'no data' rather than bugs, and private-company resolution returning resolved:false with notes. It also explains that small-molecule-only companies showing no FDA biologics is expected. This far exceeds annotation coverage with 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?

The description is information-dense and front-loaded with intent, but it is quite long and contains some redundancy with the schema (e.g., type/value interchangeable behavior is restated) and an extended list of query examples. While every sentence carries data, the overall length may slow down an agent's parsing of key directives; a tighter structure would be more effective.

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

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

Given that there is no output schema, the description compensates admirably by enumerating the return fields (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), the source fan-out, failure semantics, and input-resolution edge cases. An agent has enough context to invoke the tool correctly and interpret results for this complex multi-source profile 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% and both parameters already have descriptions, but the tool description adds important semantics: 'type' accepts company/ticker interchangeably, 'value' can be a ticker, zero-padded CIK, or company name, and name resolution goes through SEC EDGAR's company-name match. It also clarifies the private-company outcome for value, which the schema alone does not convey.

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

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

Description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It includes concrete query examples and explicitly frames itself as the holistic-view tool, which differentiates it from sibling tools like resolve_entity or compare_entities. The scope (US public company) and output highlights are unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving clear when-to-use guidance and a when-not-to-use directive. However, it does not name specific alternative sibling tools (e.g., resolve_entity) or state conditions where a single-purpose lookup should win, so it stops just short of the 5-level explicitness.

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

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

Description aligns with annotations (destructiveHint=true, idempotentHint=true). Adds context about clearing sensitive data, which goes beyond structured annotations.

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

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

Two sentences with no redundancy. First sentence states purpose, second provides usage guidance and links to siblings. Perfectly 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 single-parameter tool with no output schema, the description covers purpose and usage adequately. Could mention expected return or effect on system state but is not critical.

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 clear parameter description. Description does not add meaningful semantic detail 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?

Clearly states the action 'Delete' and the resource 'memory by key'. Distinguishes from siblings by naming 'remember' and 'recall' as paired 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?

Provides explicit conditions for use: 'context is stale, task done, clear sensitive data'. Mentions pairing with siblings but lacks explicit 'when not to use' statement.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful detail: fetches the page, extracts title/description/key links, outputs standard markdown. It does not cover potential edge cases (e.g., large pages), but is sufficient for most agents.

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 informative sentences plus a bullet list of uses. It is front-loaded with the main action and free of fluff. 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's simplicity (2 params, no output schema, good annotations), the description provides all necessary context: what it does, input requirements, output format, and typical use cases. No gaps remain.

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

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

Schema coverage is 100%, so the description adds minimal value beyond the schema descriptions. The tool description reinforces the purpose of the URL parameter and mentions link extraction, but the schema already documents both parameters adequately. 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 states a clear verb ('generate'), resource ('llms.txt file for any URL'), and purpose ('so AI crawlers can index the site cleanly'). It distinguishes this tool from its siblings, which are mostly unrelated (e.g., checks, research).

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

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

The description explicitly lists three use cases (client indexing, personal project, competitor auditing) and implies the tool is for generating llms.txt files. It does not explicitly state when not to use or name alternatives, but the context is clear and no sibling tool offers similar functionality.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds beyond that by detailing the returned fields (id, type, etc.) and the optional include_inactive parameter effect. 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 two sentences with no wasted words. The first sentence states the primary purpose and output; the second provides usage context. Very efficient.

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

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

The description covers the operation, return fields, and usage context. Given the simple nature of the tool (one optional parameter, no output schema), it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% and the schema already provides a description for the include_inactive parameter. The description does not add extra semantic information beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the resource and action. It also lists the return fields, making the purpose unambiguous. No sibling tool performs a similar list function, so differentiation is not needed.

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

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

The description explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel. This gives clear when-to-use guidance and connects to sibling operations (subscribe, unsubscribe).

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

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

Annotations are all false and offer no safety cues, so the description carries the full burden. It discloses rate limiting (5 per day), the claim_token follow-up mechanism, daily digest reads affecting roadmap, and a privacy/format constraint (don't paste end-user prompt). This is rich behavioral context well beyond what annotations provide.

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

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

Although lengthy, every sentence adds new information: purpose, criteria, exclusions, content rules, follow-up mechanics, rate limits, and pricing. The structure is front-loaded with the core purpose and organized logically; no filler 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?

The tool has a nested context object and no output schema, yet the description covers the entire workflow: when to file, what to include, what to expect (claim_token), how to check status, and constraints (rate limit, free). The sibling list confirms this is a standalone feedback channel, so all necessary context is present.

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

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

The schema already covers 100% of parameters, but the description adds meaning: it explains the claim_token parameter's special usage (pass with no other arguments to read status) and provides message guidance ('1-2 sentences typical') beyond the schema's character limit. This enhances actionable 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' using a clear verb and resource (Pipeworx feedback). It clearly distinguishes itself from sibling tools by focusing exclusively on reporting feedback about Pipeworx tools, not on investigation or data retrieval.

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 enumerates when to use: bug, feature/data_gap, praise. It provides a strong exclusion: if the tool came from a different MCP server, file it there instead, and gives a decision rule ('Pipeworx tool names are the ones this connection lists'). This leaves no ambiguity about applicability.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral traits: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. This adds value beyond annotations, though authentication needs or rate limits are not discussed.

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, front-loaded with purpose, then uses cases, then technical details. Every sentence adds value. No fluff.

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

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

Given one optional parameter, no output schema, and annotations covering safety, the description is complete. It covers caching, data source, privacy. No missing critical info. Could mention pagination or output format, but not essential.

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

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

Schema coverage is 100%, so baseline is 3. Description explains the window parameter's effect: shorter windows for hot now, longer for steady-state demand, and notes default '24h'. This adds meaning beyond the schema enum description.

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

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

Clearly states the tool returns top tools, packs, and call volume over a window. Uses specific verb 'Returns' and specifies resource 'Pipeworx trending data'. The use cases differentiate it from sibling tools like 'ask_pipeworx' or 'discover_tools'.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and aligning use case. Does not state when not to use, but the context is clear enough. No explicit alternatives mentioned, but the tool itself is about trending data, so it's distinct.

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

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

The description adds significant context beyond annotations, including internal workings (Jaccard similarity, partition filter, fill check logic) and edge cases (skipped_low_similarity, placeholders). No contradiction with annotations (all true).

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 structured but verbose, including many implementation details (e.g., Jaccard threshold, partition filter percentage). It could be more concise while retaining 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?

The description covers main aspects: modes, response structure, fill check, and references another tool. No output schema, but the text explains returns. Adequate 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%, and the description adds meaning by explaining the purpose of each mode and the internal algorithm. It does not oversell but complements the schema well.

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, with specific modes (no args, event, topic). It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly advises when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scan. It also explains the fill check and warns against trading when realizable edge is <= 0, but does not compare to sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds extensive behavioral details: caching (1h KV-level), exclusion of Fed bets from ranking, diagnostic information for empty segments, and specifics about slippage and edge calculation. No contradictions.

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

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

The description is long but well-structured with clear sections: opening purpose, segment details, opportunity fields, knobs, and response format. It front-loads the main purpose and uses line breaks for readability, 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 complexity (9 parameters, no output schema), the description thoroughly explains the return structure (by_segment with detailed segment definitions, fed_candidates, _diagnostics) and the fields in each opportunity. It covers all necessary information for an agent to use 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 description coverage is 100%, but the description adds significant meaning beyond parameter names and descriptions. For example, it explains the tradeable-edge knobs (min_liquidity, max_spread_pp) and the distinction between min_kelly and min_partition_leg_kelly, clarifying their roles in filtering.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and 'Built for "what should I bet on today"', clearly identifying the verb (scan, return) and resource (Polymarket markets). It distinguishes from sibling tools by detailing the unique model families and segments.

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

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

The description provides clear context for use (daily betting discovery) and mentions that agents can avoid paging hundreds of markets. However, it does not explicitly state when not to use this tool or compare it with siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds detailed behavioral context: reads daily snapshots, returns tracked[], expired[], snapshot_dates[], explains edge_pp_net signing, trend classification, decay calculation, lifespan, and limits (60-day TTL, not intraday). 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 informative and well-structured (purpose, args, response, limits) but somewhat lengthy. Every sentence adds value, though it could be slightly more concise without losing meaning.

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

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

No output schema exists, so description fully explains return structure: tracked[], expired[], snapshot_dates[] with field meanings, trend/decay logic, and limitations. Complete for a time-series analysis tool with complexity.

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

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

Schema coverage is 100%. Description adds value: clarifies days lookback default 14, max 30, window default '1wk' and explains it as snapshot family. Provides context about what snapshots represent, exceeding schema descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It identifies the resource (daily polymarket_edges snapshots) and action (tracking trends), distinguishing it from sibling tools like polymarket_edges.

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

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

The description implies usage by contrasting fresh vs. aged edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), but does not explicitly state when not to use this tool or provide direct comparisons to alternative sibling tools.

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

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

No annotation contradiction. Description adds behavioral context beyond annotations: walks ladder, returns slippage, verdicts, warnings about partial fills and unhedged positions. Annotations (readOnlyHint, idempotentHint) are consistent and description augments them with important operational details.

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?

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). However, description is fairly long and could be slightly more concise without losing critical information. Front-loaded with core purpose.

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

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

Despite no output schema, description thoroughly explains return values for both modes, including edge cases (thin legs, forced directional risk). Covers all inputs, defaults, limitations, and practical usage context. Very 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%. Description adds extra meaning: explains mode-dependent behavior of side and size_usd, default auto-detection for basket, clamping range. Enhances parameter understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and differentiates itself from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable, partial fills cause unhedged directional risk).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: it explains safety fields (compatibility_warning, compatibility_codes), how matching works (token-overlap matcher), that unclassified legs are never paired, the meaning of temporal_alignment_unknown (not the same as aligned), fee disclosure, and limitations on gross vs net spreads. This far exceeds the annotation baseline and provides deep transparency about the tool's behavior.

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

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

The description is long but dense with relevant information. It is well-structured: core purpose first, then modes, then response safety fields, then codes and examples. Every sentence contributes meaning (e.g., the fees note, counters, rare signal warning). While it borders on lengthy, the complexity of the tool justifies the length, and the organization makes it scannable.

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

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

With no output schema, the description bears full responsibility for explaining the response. It does so thoroughly: response format (leg-by-leg prices, spread array), safety fields (compatibility_warning/codes), per-entry flags, skipped_unclassified, temporal_alignment, fees_note, and counters. It also covers edge cases (unknown metric types, null alignment, warnings on returned pairs). No critical aspect of calling or interpreting results is missing.

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

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

Schema coverage is 100% (each parameter has a description). The description adds value by explaining the relationship between parameters: topic triggers pre-mapped shortcuts, while explicit tickers override the mapped side. It also clarifies that both modes use the same matching logic and that the response details apply to both. This goes beyond the schema's per-field descriptions, though some meaning could be even more explicit (e.g., whether parameters are mutually exclusive).

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which is a specific verb-resource pair. It distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on the spread across venues and explicitly mentioning the two venues. The two-mode operation (topic shortcuts vs explicit tickers) further clarifies what it does.

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

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

The description explains when to use the tool (for cross-venue spreads) and outlines both modes with concrete examples. It warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable', which is useful guidance. However, it does not explicitly compare against sibling tools (e.g., polymarket_arbitrage) or state conditions for choosing this over others, leaving some inference to the agent.

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. Description adds key behavior: omitting key lists all saved keys, and scoping to identifier. 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, front-loaded with main action, no wasted words. Includes examples and pairing info efficiently.

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

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

Complete for a simple retrieval tool with one parameter and annotations. Covers purpose, usage, scope, and relationship with sibling tools.

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 clear description for 'key' parameter. Description rephrases but adds only minor context (pairing with remember/forget, scoping). Meets baseline for well-documented 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?

Clear verb 'Retrieve' and resource 'value previously saved via remember' with dual mode (single key or list all). Distinguishes from sibling tools 'remember' and 'forget' 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?

Explicitly states use case: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes'. Provides scope info and pairing with remember/forget. Lacks explicit 'when not to use' but context is sufficient.

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

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

The description states that setting mark_read:true flags events as read, implying a state modification. This contradicts the annotation 'readOnlyHint': true, which indicates no side effects. The tool likely does modify read status, making the annotation misleading.

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

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

Four sentences efficiently cover purpose, return fields, filtering, state management, and alternative access. 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?

Explains return fields (source, citation_uri, payload) and key behaviors (mark_read, filter by type/since). However, the 'unread_only' and 'limit' parameters are not described, leaving gaps despite schema coverage.

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 meaningful context for 'since' (ISO timestamp) and 'mark_read' (flags events read for next call). This goes beyond the schema default descriptions, providing actionable 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 pulls fired events from the user's subscription feed, with a specific verb and resource. It distinguishes from siblings like 'list_subscriptions' and 'recent_changes' by focusing on the feed of events rather than subscription management.

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

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

Provides clear usage context: 'Polls work fine' and mentions an alternative via API endpoint. Includes filtering and mark_read behavior, but lacks explicit exclusions or when-not-to-use guidance compared to siblings.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds rich behavioral context: fans out to multiple sources, fallback logic, parameter format details (ISO date vs relative shorthand), return structure (changes grouped by source, total_changes, citation URIs), and a known API sunset issue.

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 focused and front-loaded with example queries. Every sentence adds value—no filler. It efficiently covers the tool's purpose, usage, sources, parameter formats, and return structure in a readable paragraph.

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 covers the return format (changes[] grouped by source, total_changes, citation URIs). It fully explains the multi-source fan-out, fallback behavior, parameter constraints, and provides a pointer to the sibling tool for static profiles, making it self-contained for an AI agent.

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

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

Schema coverage is 100% with each parameter having a description. The description enhances understanding by providing examples for 'since' (ISO date, relative shorthand like '30d'), explaining 'value' accepts ticker or CIK, and clarifying 'type' only supports 'company'. This adds meaning beyond the raw schema.

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

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

The description clearly states the tool provides a change feed for a company (SEC filings, news, patents) in a time window, with concrete query examples. It distinguishes from the sibling tool 'entity_profile' by contrasting dynamic vs. static profile.

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

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

Explicitly says when to use this tool vs. 'entity_profile', gives query examples, and explains the fallback mechanism (GDELT→GNews) and limitations (USPTO soft-fail). Provides clear guidance on parameter usage with examples.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral details: scoping by identifier, persistence duration (24 hours for anonymous), and that it stores key-value pairs for reuse across conversations/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?

Three well-structured sentences, front-loaded with the main purpose. Every sentence provides essential information without redundancy.

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

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

Despite no output schema, the description covers storage behavior, scoping, and persistence. The tool is a simple write operation, and the description is complete for an agent to use 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 coverage is 100%, baseline 3. The description adds examples for key (e.g., 'subject_property', 'target_ticker') and value ('findings, addresses, preferences, notes'), providing meaningful context beyond the schema.

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

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

The description clearly states the purpose: 'Save data the agent will need to reuse later'. It specifies the verb (save) and resource (key-value pair). It also distinguishes from sibling tools by mentioning 'recall' and 'forget' as complementary tools.

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

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

The description provides explicit usage guidance: use when 'you discover something worth carrying forward'. It also specifies scoping by identifier and persistence details (authenticated vs anonymous). Pairs with recall and forget, giving clear context on when to use this tool vs alternatives.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds substantial behavioral context: identifiers are 'labelled with the source that established it,' unresolved identifiers are 'stated explicitly under unresolved rather than omitted,' ambiguous matches 'assert nothing and return figi_candidates,' and enrichment 'degrades gracefully' when GLEIF/OpenFIGI are unavailable. It also explains the internal cascade through multiple lookup endpoints. This far exceeds what annotations alone convey, with 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 front-loaded with purpose and examples, but it is extremely long and densely packed with parentheticals, making it a wall of text. While every segment contains useful information, the lack of clear section breaks or bullet-like structure harms scannability. It is adequate but not concise for the amount of content.

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

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

With no output schema, the description carries full responsibility for explaining behavior, and it achieves that thoroughly. It covers input variants, ownership chains, non-equity instruments, ambiguity handling, unresolved identifiers, degradation behavior, and the benefit of replacing multiple manual lookups. Nothing critical is left unexplained for an agent to successfully invoke this 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 the description enriches both parameters considerably. For 'type,' it explains that 'company' resolves to CIK, ticker, company_name from SEC EDGAR, LEI from GLEIF, and FIGI from OpenFIGI, while 'drug' returns RxCUI + ingredient + brand. For 'value,' it clarifies accepted inputs (ticker, CIK, ISIN, or name), explains ISIN-to-LEI mapping, and provides a concrete bond-name example that directly expands the schema's warning about trailing security-class words. This adds meaning beyond the structured fields.

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 includes multiple example queries ('What's the ticker for…' / 'find the CIK for…') and explicitly differentiates itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.' It also details the supported types ('company' and 'drug') and what each resolves, making the purpose unambiguous.

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

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

'Use FIRST whenever you have a name but need an ID' is an explicit when-to-use instruction that distinguishes this tool from later lookup steps. The description also gives precise input guidance, such as 'Pass the ENTITY NAME ONLY' and warns against including trailing security-class words for bonds. However, it does not name alternative tools (e.g., entity_profile) or state when not to use this tool, so it falls short of full exclusionary guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. Description adds significant behavioral detail: probes each entity using ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. 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?

Four sentences, ~80 words, efficiently conveying purpose, mechanism, and return value. Front-loaded with main action, no redundant or verbose language.

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, internal call to another tool), the description covers what it does, how it works (probes each entity, ranks), what it returns (score, confidence, signal density), and the expected input structure. No obvious gaps.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by specifying that the first entity in the 'entities' array is treated as the 'subject' for narrative, going beyond the schema. Other parameters are adequately documented in schema.

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

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

Description clearly states the verb 'compare', resource 'AI visibility across multiple entities', and explicitly differentiates from the sibling tool 'ai_visibility_check' by specifying side-by-side comparison and ranking. Example use case further clarifies purpose.

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

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

Description explicitly frames the use case as 'competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or list alternatives. However, context from sibling tools provides differentiation.

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, idempotent, non-destructive. Description adds valuable behavioral details: fans out to multiple sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed lists timeouts. 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 a single dense paragraph containing all key information. It is front-loaded with the main purpose. However, it could be more structured (e.g., bullet points for return fields) to improve readability for agents.

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

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

Given the complexity of the tool (multiple sources, potential delays, partial failures), the description covers all essential aspects: what is returned, ecosystem scope, performance caveats, and graceful degradation. No output schema exists, but the description lists the summary block fields.

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

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

Schema coverage is 100% with descriptions. Description adds context beyond schema: scoped packages are accepted, version defaults to latest, and implies optionality of version. This adds meaning but the schema already provides solid definitions.

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

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

The description clearly states it performs a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs ('scan', 'fans out') and distinguishes itself from sibling tools by specifying ecosystem scope and alternatives for other platforms.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives 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 declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds details beyond these: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation and flagging, and each passage carries offsets. 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?

The description is a single paragraph but packs a lot of information efficiently: purpose, usage scenario, benefits, technical details, and limitations. It is front-loaded with the core purpose. Could be slightly more structured (e.g., bullet points) but no wasted words.

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

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

Given the complexity of semantic search, the description is comprehensive: it explains the use case, how it works (embeddings, windows, offsets), constraints (200K chars), and return values (offsets, similarity scores). It also mentions pairing with a sibling tool. No output schema exists, but the description adequately covers what the agent needs to know.

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 value by explaining the text parameter as document text, providing query examples, and clarifying limit as max passages (1-20, default 5). It also explains the internal mechanism (embeddings, windows), which goes beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record. It specifies the use case (when a record is too large for the prompt) and what it returns (top-N passages with offsets and similarity scores). This distinguishes it from siblings like ask_pipeworx_grounded.

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

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

It explicitly describes when to use (when a record is too big to cram into the prompt) and mentions pairing with ask_pipeworx_grounded. It provides examples (SEC 10-K, article). However, it does not explicitly state when not to use or list alternatives, but the guidance is clear.

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

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

The description provides extensive behavioral context: persistence requirement (OAuth account), delivery channels with constraints (email, sms cap, webhook auto-disable after 10 failures), and return of subscription id. This supplements annotations (non-readonly, non-destructive, idempotent) 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 a single dense paragraph but effectively front-loads the purpose and then details types and delivery. It could be more structured with bullet points, but every sentence adds value without redundancy.

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

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

Given the complexity (3 params, nested objects, multiple types), the description covers core usage, constraints, and return value. No output schema exists, but the description mentions returning subscription id and webhook secret. Minor gaps like error handling are acceptable.

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

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

With 100% schema coverage, baseline is 3. The description adds significant value by explaining type-specific parameter structures (e.g., items, topic, series_id) and delivery details including webhook signing and secret return, which is beyond schema descriptions.

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

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

The title and description clearly state the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes itself from siblings like list_subscriptions and unsubscribe by specifying the creation action and required OAuth account.

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 requires a Pipeworx OAuth account and lists supported subscription types with examples. It provides context for when to use the tool (monitoring live events) but does not explicitly state when not to use it or compare with alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about returning category-bucketed example questions with tool+argument shapes, and behavior under no-args vs topic. 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 front-loaded with example queries, then explains return format and usage. Each sentence adds value, though it could be slightly more concise. Well-structured overall.

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 an onboarding tool with one optional parameter, the description is complete: explains purpose, usage scenarios, return format, and provides examples. Compensates well for lack of output schema by describing what is returned.

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

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

Schema coverage is 100% with a description for the optional 'topic' parameter. The description adds value by explaining that omitting topic gives a full spread, providing examples of focus areas, and listing possible topic values beyond the schema examples.

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?

Title and description clearly state the tool is for onboarding, answering 'what can I ask', and providing example questions. It distinguishes itself from siblings by being the entry point for new users.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with no arguments vs with a topic. Also mentions learning how to call meta-tools, providing excellent 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 annotations (idempotentHint=true, destructiveHint=false), the description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This fully discloses the soft-deletion behavior and side-effects.

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 front-load the action ('Cancel a subscription by id.') and add only essential behavioral and constraint information. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and deactivation behavior completely. No gaps remain given the tool's low complexity.

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

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

The input schema already provides 100% coverage with a clear description for the required 'id' parameter. The tool description adds no additional parameter meaning beyond what the schema provides, justifying the 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?

The description clearly states 'Cancel a subscription by id', providing a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), giving clear context about usage constraints. However, it does not explicitly state when not to use this tool or suggest 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral nuances: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source was found. It also explains the dual-path routing and the inclusion of pipeworx:// citations, providing substantial transparency beyond what annotations convey.

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

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

The description is longer than average, but each sentence serves a purpose: trigger phrases, usage guidance, routing logic, verdict list, and important error-handling caveats. It is front-loaded with the core purpose and progressively adds detail, making it dense but efficient. Minor redundancy could be trimmed, but overall it earns its length.

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

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

Given there is no output schema, the description compensates fully by enumerating all possible verdicts, the composition of the return (actual value + citation + reasoning), and the distinct meanings of could_not_verify and unsupported. It also addresses error handling and the tool's advantage over sequential calls, making it complete 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?

The schema already fully describes both claim and tolerance_pct with examples. The description adds extra semantic value by explaining that tolerance_pct overrides the tolerance implied by the wording, suggesting 1–2% for hallucination detection, and clarifying the default behavior (implied by wording, capped at 5). This enriches the schema's baseline.

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

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

The description opens with natural-language trigger examples and states the core function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from siblings like ask_pipeworx by focusing on fact-checking and verdict generation, not general Q&A or research.

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

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

Explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR fast path) and all other claims (grounded pipeline), and even notes it replaces 4–6 sequential calls, giving clear context for 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.