Facebook_ads

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds behavioral context: costs for Anthropic are user-borne, the tool returns per-model scores with specific fields, and it is a probe (no side effects). This goes beyond annotations without contradiction.

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

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

The description is a single paragraph but front-loads purpose and then details parameters and use cases. It is concise without being terse, though could be slightly more structured (e.g., bulleted output format).

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

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

Given no output schema, the description describes the return structure (per-model {score, confidence, signals, raw_response} + combined view) and mentions required parameter entity. All necessary context for correct usage is provided.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains default model, that models array is optional, how _apiKey is used, and that context helps disambiguate. This enriches the parameter documentation beyond the schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the verb 'probe' and the unique resource 'AI visibility', distinguishing it from sibling research tools like deep_research or compare_entities.

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

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

The description gives explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model and when Anthropic requires an API key. However, it does not directly state when not to use it or which siblings serve as alternatives, leaving some implicit 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 cover read-only, idempotent, and open-world behavior, so the description's job is lighter. It adds meaningful behavior context by revealing this is a dispatcher that routes to one of 5,798 tools, fills arguments, and returns stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and uses examples to make scope concrete. It is slightly long as one block and the closing phrase 'START HERE for most questions — for most fact-based questions' is mildly redundant, but each section generally 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 router tool with no output schema, it explains the input, the internal delegation behavior, and the output ('structured answer with stable pipeworx:// citation URIs'). It is complete enough for most calls, though edge cases such as ambiguous questions, failure handling, and when to choose a Pipeworx variant or deep_research instead remain unaddressed.

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 documents the question parameter plus its aliases, so the baseline is 3. The description earns above baseline by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and broad domain guidance that clarify expected natural-language input. It adds no parameter-level format constraints beyond that.

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 action and resource: routes a natural-language question to one of 5,798 tools across 1,517 verified sources and returns a cited structured answer. It clearly contrasts the tool with web search and lists concrete data domains. However, it does not distinguish itself from the close sibling names ask_pipeworx_beta and ask_pipeworx_grounded, so it stops short of full sibling differentiation.

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 positive triggers: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks "what is", "look up", ...', and concrete example queries. It also names web search as the alternative and says to use this tool even if web search could answer. It lacks an explicit when-not-to-use rule or routing guidance among Pipeworx variants such as ask_pipeworx_grounded/deep_research.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety profile is covered. The description adds useful context about the experimental edge, the comparison against stable router, fallback behavior ('Falls back to nothing — this IS a full working router'), and the retired candidate date, which is more than annotations provide.

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

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

The description is compact yet informative, front-loading the key identity ('Beta version of ask_pipeworx') and the key usage instruction. A little wordy near the end ('the last was retired on outcome evidence 2026-07-26'), but that detail is relevant for transparency.

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

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

Given the tool's low complexity (one meaningful param, no output schema needed, simple alias semantics), the description covers identity, current behavior, usage, and fallback. It lacks a mention of any rate limits or response format specifics, but for a read-only router that mirrors a sibling, this is nearly 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%, so the description doesn't need to explain parameters deeply; the schema handles that. The description mentions 'same arguments' and tells agents to use it like ask_pipeworx, providing adequate routing-level guidance 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 is a beta variant of ask_pipeworx, identical in tools/arguments/response shape, with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx sibling and explicitly tells how to use it.

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

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

Explicitly says to use exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It also clarifies no candidate is active right now, so behavior currently matches ask_pipeworx exactly.

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 substantial behavior beyond annotations: the exact success response shape, the refusal contract with specific refusal_reason values, and the constraint that extraction uses ONLY tool results. There is no contradiction with the read-only, idempotent, open-world annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, output contract, usage criteria, and cost trade-off. It is front-loaded with the key differentiator and avoids 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?

Despite having no output schema, the description fully specifies return fields, refusal modes, routing behavior, source scope, and when to prefer the alternative. An agent has everything needed to decide whether to invoke it and what to expect.

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

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

The input schema has 100% coverage of the required question parameter and its aliases, so the description does not need to add parameter syntax. The description adds use-case context but no parameter-level semantics beyond the schema, matching the baseline of 3.

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

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

The description clearly defines a specific mode: a hallucination-resistant, grounded answer extractor that works by routing to underlying tools and using only the tool result. It explicitly differentiates from sibling ask_pipeworx by emphasizing extraction, evidence, and refusal behavior.

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

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

It explicitly states when to use this tool: when an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative, ask_pipeworx, and says to prefer it for casual lookups, including the cost trade-off of one 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?

Annotations declare the tool as readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral detail: fan-out pattern, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, wide-spread handling, and resolution-rule risk. No contradictions with annotations.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs. While front-loaded with purpose and usage, it includes extensive detail on response shapes and edge cases that could be streamlined. Not all sentences are essential for basic understanding.

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

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

Given the tool's complexity, 3 parameters, no output schema, the description covers all essential aspects: purpose, input formats, classification taxonomy, fan-out examples, response structure, resolver contract, parent event extraction, news fallback, safety mechanisms, wide-spread tradeability, and resolution-rule risk. Extremely 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%, so baseline is 3. The description does not add significant meaning beyond the schema: it explains the 'market' parameter can be a slug, URL, or question text (already in schema), and 'depth' and 'include_raw' are described similarly. No new semantic value.

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

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

The description explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). This clearly distinguishes it from sibling tools like polymarket_edges or validate_claim.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also explains behavior for low-confidence matches and closed markets, but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds further behavioral context: one parallel call, correct handling of off-calendar fiscal years, results sorted by primary metric, returns citation URIs, and replaces 8–15 sequential lookups. 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 front-loaded with example queries and is concise overall, though could be trimmed slightly. Every sentence adds value, but some redundancy (e.g., 'side-by-side' vs 'parallel'). Still well-structured and efficient.

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

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

No output schema provided, but description explains return format: sorted by primary metric, paired data with citation URIs. Covers behavioral nuances like fiscal year handling. Given complexity and limited parameters, description is complete and helps agent understand expectations.

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% (both parameters described). The description adds meaning beyond schema: for 'type' it specifies what data is pulled (company: revenue, net income, cash, debt; drug: FAERS, FDA approvals, active trials). Examples for 'values' are given. Adds value over baseline, but schema already covers basics.

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 explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and distinguishes from sequential lookups. It clearly defines the purpose with specific verb (compare) and resource (entities).

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases like 'X vs Y' or 'which is bigger'. It tells the agent 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?

With readOnly, openWorld, and idempotent annotations, the description adds substantial behavioral detail: it decomposes questions into facets, routes to tools in parallel, never invents answers, includes gaps[], returns contradictions[] for standard/thorough depths, retries unanswered facets, and cites fetchable pipeworx:// URIs only when resolvable. It also discloses account tier requirements and latency expectations. No contradictions with annotations.

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

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

The description is long, but every section earns its place: access prerequisites, core distinction, process, output format, gap handling, depth semantics, citation guarantees, and latency. It is front-loaded with the most critical operational constraint (account required). The only minor cost is density, but no content is redundant.

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 fully carries the burden of explaining return values. It does so thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers prerequisites, latency, and edge cases like non-fetchable citations. An agent has everything needed to call and interpret the result.

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?

Though the schema already documents both parameters, the description significantly enriches them: it explains that 'question' is expected to be broad/multi-part and natural language, and it details what each depth value ('quick', 'standard', 'thorough') does in terms of hops, gap recovery, contradictions, and paid access. This goes well beyond the schema's enum descriptions.

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

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

The description states a precise verb and resource: it conducts 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups. The clear focus on broad/multi-part structured-data questions makes its 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?

It explicitly tells agents when to use this tool vs alternatives: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' It also specifies the best-fit scenario: broad/multi-part questions over structured data. This is exemplary 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, idempotentHint, and non-destructive nature. The description adds behavioral context: results include curated examples and are ready to call directly, plus default/max limit for the limit parameter. 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 well-organized and front-loaded with the core purpose. It is fairly dense but concise given the amount of information; one could argue minor redundancies like listing many domains, but it serves as a helpful enumeration.

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

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

For a tool that returns a list of discovered tools, the description adequately covers the input (natural language query), output (tools with schemas ready to call), and usage context. No output schema is needed because the description explains the return format sufficiently.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context about accepting natural language and lists aliases, but does not provide semantic details beyond what the schema already offers for individual parameters. Baseline 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and explains the output includes names, descriptions, and full schemas ready to call, distinguishing it from siblings like search_within.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies not to use when you already know the specific tool.

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

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

The description goes well beyond the read-only/idempotent annotations by disclosing source fan-out behavior, the USPTO PatentsView API sunset with soft-fail, the expected empty fda_products for small-molecule-only companies, and the meaning of sources_used/sources_failed. It also explains how private companies resolve. There is no contradiction with the annotations.

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

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

The description is long but densely packed and front-loaded with query examples and the 'always prefer' directive before enumerating output sections. Some example phrases are near-duplicates, so it is slightly less concise than ideal, but overall the structure is logical and every substantive section 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?

With no output schema, the description fully documents the return shape: cik, resolved fields, recent_filings limits and URIs, fundamentals fields, patents, federal contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also explains failure and empty-result semantics. Nothing needed to invoke the tool correctly 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%: both `type` and `value` are clearly documented in the schema. The description restates the accepted value shapes (ticker, CIK, company name) and the interchangeability of `type`, but adds little new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with concrete invocation examples and clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company), the action (profile/research), and explicitly contrasts itself with 'single-pack SEC/XBRL/news lookups' so an agent can differentiate it from related 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?

It explicitly directs usage: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also describes what happens for private companies (resolved:false with a notes line) and notes that `type` accepts 'company' or 'ticker' interchangeably. This gives clear when-to-use, when-to-avoid, and alternative-condition guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds no new behavioral context beyond listing metrics. It does not contradict annotations, but the erroneous 'account_id' requirement could confuse the agent about parameter usage. Score 3 because annotations carry the burden.

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 and adequately front-loaded with verb and resource. However, the spurious 'account_id' adds noise. Most information is useful, but the error detracts from conciseness. Still, it is appropriately sized for the tool's complexity.

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

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

Given the output schema exists (which explains return values), the description covers basic functionality. It lists examples of metrics but omits cpm, reach, actions, action_values mentioned in schema. It does not explain date_preset vs time_range usage. The incorrect parameter again weakens completeness. Adequate but not 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 coverage is 100% with descriptions for all 5 parameters, so the description adds minimal value. It mentions 'account_id' (not in schema) and 'campaign_id', but does not explain date_preset/time_range interplay or default metrics. The incorrect parameter reduces trust. Baseline 3 reduced to 2 due to inaccuracy.

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

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

The description clearly states the verb 'Get' and identifies the resource as 'campaign performance metrics'. It lists specific metrics (impressions, clicks, spend, etc.), distinguishing it from siblings like fb_get_campaign (which likely returns campaign details) and fb_list_campaigns (which lists campaigns but not metrics).

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 required parameters but does not provide guidance on when to use this tool versus alternatives. It lacks explicit when-not or context for selection, and contains an inaccuracy: it claims 'account_id' is required, but the input schema only requires 'campaign_id'. This misstatement reduces clarity for 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent with a read operation. However, the description claims it 'Requires account_id and campaign_id', while the schema only requires campaign_id. This inaccuracy reduces transparency and could mislead an agent.

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, concise sentence. However, it includes an inaccuracy (account_id requirement). It is front-loaded with purpose but lacks structure and precision.

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 an output schema exists and annotations cover safety, the description should add usage context, such as when to retrieve detailed info vs insights. It does not explain the return value structure or differentiate from sibling tools, leaving the agent under-informed.

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 documented. The description adds no semantic value beyond the schema; it incorrectly states that account_id is required, and the mention of 'targeting' in returned fields is not reflected in the schema's default fields list.

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

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

The description clearly states the verb 'Get' and the resource 'detailed campaign info', listing specific fields like name, budget, status, schedule, and targeting. However, it does not distinguish this tool from sibling tools like fb_campaign_insights or fb_list_campaigns, which could also retrieve campaign data.

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?

No guidance on when to use this tool versus alternatives. The sibling list includes fb_campaign_insights (for metrics) and fb_list_campaigns (for listing), but the description does not clarify that this tool is for detailed configuration info.

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. Description adds 'all accounts you have access to' but no additional behavioral context.

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

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

Two sentences, no redundancy, immediately states function and output. Ideal length for a simple list tool.

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

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

With output schema present and rich annotations, the description covers core functionality. Lacks pagination or error notes but sufficient for basic use.

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 describes both parameters (limit, fields) adequately. Description does not add new meaning beyond default field values mentioned.

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 lists all accessible Facebook ad accounts, specifying return fields (IDs, names, status). This distinguishes it from sibling tools like fb_list_campaigns.

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?

No guidance on when to use this tool vs alternatives (e.g., fb_list_adsets for adsets). No mention of prerequisites or when to filter with parameters.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds value by specifying the returned fields (names, IDs, status, budgets, targeting), providing transparency about the output without contradicting annotations.

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

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

The description is a single, concise sentence with an inline example, efficiently conveying the tool's purpose and usage without unnecessary words.

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

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

For a simple listing tool with an output schema, the description adequately covers the essential information. It does not address pagination or limit handling, but the schema provides these details, so it is sufficiently 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?

While the input schema has 100% description coverage, the description includes an example with 'account_id' which is not a parameter in the schema, potentially misleading agents. The description does add context beyond the schema but introduces inaccuracy.

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 'List ad sets in a campaign' with a specific example, and the tool name is self-explanatory. It distinguishes from sibling tools like fb_list_campaigns and fb_list_ad_accounts by specifying the resource type (ad sets) and the required campaign context.

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 for listing ad sets within a specific campaign but does not provide explicit guidance on when to choose this tool over alternatives like fb_list_campaigns or fb_list_ad_accounts, nor does it mention prerequisites or limitations.

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 context on return fields (names, IDs, status, objectives), which is helpful. Does not contradict 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?

Single sentence with an example; concise and front-loaded. Could add more structure but no unnecessary 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 full schema coverage, annotations, and an output schema (not provided but exists), the description is adequate for a listing tool. It covers key return fields and usage context.

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

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

Schema coverage is 100% with full parameter descriptions. The description only adds a usage example for act_account_id format, adding minimal meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states the tool lists campaigns in a Facebook ad account, specifying the verb 'list' and the resource 'campaigns in a Facebook ad account'. Distinguishes from sibling tools like fb_get_campaign (single campaign) and fb_campaign_insights (insights).

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

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

Provides an example of usage with account_id format, implying context. However, does not explicitly state when to use versus alternatives or when not to use it. Sibling tool names provide implicit 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 declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' matches. It adds no additional behavioral traits beyond the annotations, only slight context about sensitive data.

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

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

Two sentences, front-loaded with the action, no unnecessary words. Every sentence serves a purpose.

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

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

For a simple tool with one parameter and no output schema, the description plus schema fully cover its behavior and usage, leaving 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 has 100% coverage with a clear description for the 'key' parameter. The description does not add any extra meaning beyond what the schema already provides.

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

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

The description clearly states the tool deletes a memory by key, with a specific verb ('Delete') and resource ('memory by key'). It distinguishes from siblings like 'remember' and 'recall' which store/retrieve.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. Also mentions pairing with 'remember' and 'recall', giving clear guidance on alternatives.

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

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

The description details the steps (fetch, extract, emit) beyond what annotations provide (readOnlyHint, idempotentHint). It aligns with annotations and adds context about the generated output format. No contradictions; however, it does not cover edge cases like invalid URLs.

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

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

Three sentences, each serving a distinct purpose: purpose, process, use cases. Front-loaded with key verb and resource. No redundant information.

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

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

For a tool with 2 simple parameters and no output schema, the description fully covers what the tool does, the input, and the output (text blob for site-root). It is complete and intuitive.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for url and max_links; it only contextualizes the overall process.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt). It details the process—fetching page, extracting title/description/key links, and emitting standard markdown—and distinguishes it implicitly from siblings like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists three explicit use cases: getting a client's site indexed, drafting for own project, and auditing competitors. It provides clear context for when to use this tool, though it does not include explicit exclusions or when-not scenarios.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by listing the exact return fields and noting that inactive subscriptions are excluded by default, complementing the annotations.

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

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

The description is concise with three sentences, front-loading the core purpose. 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 a single optional parameter and no output schema, the description adequately covers the tool's functionality and usage. It could potentially mention if there is pagination, but not 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?

With 100% schema description coverage, the schema already documents the single parameter well. The description does not add extra parameter information beyond the schema, so 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 active subscriptions for the caller and specifies the return fields. It distinguishes well from siblings like 'subscribe' and 'unsubscribe' which handle creation and removal.

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 before adding or canceling subscriptions, providing clear context. It does not explicitly compare with alternatives but the use cases are well defined.

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 minimal (all false) and do not contradict the description. The description goes beyond annotations by disclosing rate limits (5 per identifier per day), the claim_token mechanism for tracking, that it is free and does not count against quota, and that the team reads digests daily. This is rich context for an agent deciding to invoke 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?

While longer than average, every sentence adds value: purpose, use cases, exclusion, token mechanics, rate limits, and quota. The structure front-loads the core purpose and flows logically, 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?

Despite no output schema, the description fully explains what the agent will get back (a claim_token if no account) and how to use it. It covers prerequisites, side effects, and limitations, making the tool's behavior predictable. Given the tool's complexity, this description is complete.

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

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

Schema covers all 4 parameters with descriptions, so baseline is 3. The description adds significant cross-parameter meaning: it explains how claim_token is used (pass it back to read reply), maps type values to real-world scenarios, and instructs on message content formatting. This elevates it above the baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates distinct feedback types (bug, feature/data_gap, praise) and explicitly scopes itself to tools served by this Pipeworx connection, distinguishing it from all sibling tools like ask_pipeworx.

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

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

Provides explicit when-to-use triggers mapped to feedback types, and an explicit exclusion: tools from other MCP servers should be reported there, not here. It also offers guidance on how to phrase feedback (in terms of Pipeworx tools/packs, not end-user prompts), which is actionable.

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

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

Description adds meaningful context beyond annotations: source (CF analytics-engine), no PII, caching policy (5min-1h), and self-aggregating nature. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. 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 compact yet covers all essential information: what it returns, three use cases, data source, privacy, and caching. No redundant sentences. Front-loaded with the key output, then use cases, then technical details.

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

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

Given no output schema, description adequately explains return content (top tools, top packs, total call volume) and adds caching and source details. For a simple read-only tool with one optional parameter, the description is fully complete and informative.

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

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

Only one parameter (window) with full schema description (enum, description). The description adds value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the semantic difference beyond the enum values. Schema coverage is 100%, so baseline is 3, but the added context justifies a 4.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window. The verb 'returns' is specific, and the resource (trending usage from Pipeworx) is well-defined. It distinguishes from siblings like 'discover_tools' by focusing on what others call, not discovery.

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 concrete use cases: discovering hot data sources, confirming canonical tool, and checking alignment. Does not specify when not to use or provide alternative tools, but the guidance is clear and actionable. Minor gap: no explicit exclusion of other use cases.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds significant detail: algorithms (monotonicity violations, partition checks), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check (using arbitrage.fill_risk), and response fields. 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 thorough but not overly verbose. It is well-structured: high-level purpose, mode details, filters, response, and fill check. Every sentence adds value, though a slight trim could improve conciseness.

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

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

For a complex tool with no output schema, the description covers modes, algorithms, filters, response structure, and mentions a related tool (polymarket_fill_risk). Could explicitly state real-time vs historical data, but overall 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 provides 100% coverage with descriptions for both parameters. Description adds substantial context: examples of slugs, clarification that full URLs are accepted, and explanation of what happens when no args are passed (trending_scan).

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and explains the core logic, making it specific and actionable.

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

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

Provides explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Also explains default behavior with no args. Could improve by differentiating from sibling tools like polymarket_edges, but the purpose is distinct enough.

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

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

The description adds extensive behavioral context beyond annotations: caching (1h at KV level), model details (crypto_price, news_momentum), tradeable-edge knobs, Fed exclusion rationale, diagnostics for empty segments. No contradiction with annotations.

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

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

The description is well-structured with important info upfront and clear grouping of segments, opportunities, and knobs. However, it is quite long and includes some implementation details that could be trimmed.

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

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

Given the complexity (9 parameters, no output schema), the description covers purpose, segments, edge calculation, response structure, diagnostics, and caching. It is complete enough for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description provides some contextual grouping (e.g., tradeable-edge knobs) but does not add significant new 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 a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings by focusing on Pipeworx disagreement and not paging hundreds of markets.

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 says it's 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets,' providing clear context. However, it does not explicitly mention when not to use it or point to alternatives like polymarket_arbitrage.

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

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds extensive behavioral info: returns tracked/expired opportunities with time-series, trend, decay, first_seen, snapshot dates. Also discloses that decay is from daily closes not intraday, and history starts from snapshot enablement.

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 purpose and answer, then details response structure and limits. Every sentence adds value, though the response structure section is lengthy. Could be slightly more condensed, but no superfluous information.

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

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

No output schema exists, but the description fully specifies the response: tracked array with full time-series fields, expired array with lifespan, snapshot dates. Covers limits (60-day TTL, snapshot dependency, decay granularity). Complete for a tool with 2 optional params.

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

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

Input schema already covers both parameters with descriptions (100% coverage). The description adds default and max for 'days', and for 'window' lists explicit options and default '1wk', plus explains snapshot family concept. This adds meaningful context beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering when an edge appeared and if it's shrinking. It distinguishes from sibling polymarket_edges by focusing on time-series and trend analysis, not just current 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 tells when to use: to know how long an edge has existed versus when it's fresh. Contrasts fresh wide edge vs 3-week-old wide edge, implying when not to use (if only current edge matters, use polymarket_edges). Also states limits like 60-day TTL and snapshot dependency.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), explains basket mode risks (thin_legs, forced_directional_risk). 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 fairly long but well-organized with clear section breaks (SINGLE-MARKET, BASKET) and bold labels. Key information is front-loaded (purpose and requirement). Could trim some redundant phrasing, but every sentence adds value and the structure aids quick scanning.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is highly complete. It enumerates all return fields for both modes, explains edge cases (thin books, partial fills, unhedged risk), and provides practical usage context (dominant loss mode). No output schema needed with this level of detail.

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 descriptions are minimal. The tool description adds significant semantic value: clarifies default values, explains the dual interpretation of size_usd (spend vs target proceeds for single-market, settlement notional for basket), details side auto-detection logic, and provides context for default 1000 with clamp range.

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+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and provides enough detail to differentiate from sibling tools 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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of misuse, such as partial basket fills converting an arb into an unhedged directional position, providing clear when-not-to-use guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations: it discloses that matching is keyword/overlap based, that Kalshi fees are not modeled, that spreads are gross, that unclassified legs are never paired, and that null temporal_alignment does not mean aligned. This is exemplary behavioral disclosure.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded key information. It is quite long, but nearly every sentence carries safety or matching context; a lighter edit could preserve the value while reducing length.

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

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

For a complex tool with no output schema, the description covers response fields, compatibility codes, skipped-leg counters, fee caveats, and matching limitations thoroughly. The only notable omission is behavior when called with no parameters at all, especially since all parameters are optional.

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

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

The schema already covers all three parameters at 100% coverage, and the description adds meaningful mode semantics: topic pre-maps events while the explicit parameters override the mapped side, and both modes run the same matcher. It does not add much beyond that, but the mode relationship is genuinely useful.

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 by naming the exact deliverable — a cross-venue spread between Kalshi and Polymarket for the same resolving question — which immediately separates it from Polymarket-only siblings. The two-mode breakdown and response summary make the tool's function concrete and unambiguous.

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

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

It clearly explains when to use the topic shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics often return compatibility warnings. It does not explicitly route the agent away from sibling tools like polymarket_edges or polymarket_arbitrage, so it stops just short of a 5.

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

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

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

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

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

The description is four sentences, dense with information, and front-loaded with the core purpose. Every sentence adds value, and no words are wasted.

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

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

Given the tool's simplicity (one optional parameter, no output schema, good annotations), the description fully covers purpose, usage, behavior, and relationships. No gaps remain for an AI agent to misinterpret.

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

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

Schema coverage is 100% with a clear parameter description. The description adds value by explaining the effect of omitting the key (list all) and the scoping context, which enhances understanding beyond the schema alone.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly states the resource ('value previously saved via remember', 'all saved keys'). It explicitly distinguishes from sibling tools 'remember' and 'forget' by mentioning them by name.

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 ('look up context the agent stored earlier') and explicitly pairs it with 'remember' and 'forget'. It does not explicitly state when not to use it, but the context is sufficient for an AI agent to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds detail about returned fields (source, citation_uri, raw payload), the effect of mark_read on future calls, and polling safety, providing rich behavioral context beyond annotations.

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

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

The description is a single well-organized paragraph: purpose, return fields, filters, mark_read behavior, polling note, and alternative URL. Every sentence contributes essential information with no redundancy.

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

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

Given no output schema, the description adequately describes the return structure and key behaviors. It covers filtering, mark_read effect, and polling. Minor missing details like pagination or error handling are acceptable given schema completeness and annotations.

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

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

Schema coverage is 100% so baseline is 3. The description explains the effect of 'mark_read' and mentions examples for 'type' and 'since', adding incremental value 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 'pulls fired events from your subscription feed' and 'returns the most recent alerts', using specific verbs and resources. It distinguishes from sibling tools like 'list_subscriptions' and other unrelated tools by focusing on alert 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?

The description mentions 'Polls work fine' indicating suitability for frequent polling and provides an alternative URL for scripts/dashboards. However, it does not explicitly compare to other tools for when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds rich behavioral details: fans out to SEC EDGAR, GDELT/GNews fallback, USPTO soft-fail, output structure with grouped changes and citation URIs. No contradictions.

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

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

Description is dense with information but flows well from example queries to details. Could be slightly more structured (e.g., bullet points for sources), but every sentence serves a purpose.

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

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

Given no output schema, the description adequately describes return format (grouped changes, count, citation URIs). Covers multiple data sources, fallback logic, parameter details, and alternative tool. No missing information for typical use.

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, but description goes further: elaborates on 'since' formats (ISO date vs relative shorthands like '7d', '3m'), clarifies 'value' accepts ticker or CIK, and constrains 'type' to 'company'. This adds meaning beyond the schema.

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

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

The description uses clear, example-driven language ('What's new with X', 'latest on Y') and explicitly distinguishes from sibling tool 'entity_profile', making the tool's purpose immediately obvious.

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 via query examples and a direct comparison to 'entity_profile'. Also details data source fallback behavior (GDELT→GNews) and 'since' format options, leaving no ambiguity.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false. The description adds behavioral context: storage as key-value pair scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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 four sentences, front-loading the main purpose, and every sentence adds value. No redundancy or unnecessary 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?

Given the simple two-parameter input and no output schema, the description fully covers usage context, data lifetime, and pairing with recall/forget. It is complete for an agent to understand when and how to invoke the tool.

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

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

Although schema descriptions already define key and value, the description adds semantic examples and use cases (like 'subject_property', 'target_ticker') that clarify expected format and content 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 saves data for reuse across conversations or sessions, specifying the verb 'save' and resource 'data'. It distinguishes itself from siblings by naming 'recall' and 'forget' 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?

The description explains when to use ('when you discover something worth carrying forward') and gives examples (resolved ticker, target address, user preference, research subject). It also mentions scoping and persistence details, and refers to alternative tools.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial extra behavior: unresolved identifiers are stated under 'unresolved' instead of omitted, ambiguous matches return 'figi_candidates' and assert nothing, and LEI/FIGI enrichment 'degrades gracefully' if external sources are down. This is exactly the kind of context agents need beyond structured hints.

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

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

The description is long and dense, but it is front-loaded with the core purpose and organized under SUPPORTED TYPES with sub-details for company and drug resolution. Some parentheticals are heavy, but the complexity of the domain justifies much of the 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 well by explaining return semantics: labeled source identifiers, unresolved fields, figi_candidates for ambiguity, and graceful degradation. For a two-parameter, read-only lookup tool, an agent has enough context to invoke it correctly in diverse situations.

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 meaningful nuance beyond the schema: ISIN is accepted as an input form, and it warns agents to pass the entity name only, not the full noun phrase, because 'trailing security-class words match nothing'. This materially improves invocation correctness.

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

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

The description opens with concrete user-phrase examples and a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers'. It clearly distinguishes the tool's purpose from siblings by stating that these identifiers are what 'other tools require as input'.

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 an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported entity types and input forms, which helps agents route requests. It does not explicitly name alternative tools or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations indicate safe, read-only, idempotent behavior. Description adds that it probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. No contradictions and provides useful behavioral context.

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

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

Two sentences; first describes action, second gives use case and output. 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?

Despite missing output schema, description sufficiently explains output format (ranked list with score, confidence, signal density) and input requirements. Complete for this tool's complexity.

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

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

Schema coverage is 100%; description adds context about first entity being the subject and clarifies _apiKey purpose. Provides value beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, and ranks by score. It distinguishes from sibling ai_visibility_check which is for single entities.

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

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

Explicitly suggests use for competitive AI-marketing audits with an example. Implicitly contrasts with single-entity probes but does not explicitly list alternatives or when-not-to-use.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds behavioral details: partial failures (bundlephobia can take 5-30s, sources_failed lists failures), graceful degradation, and return structure (summary block, per-advisory detail, links, recent alternative versions). No contradiction with annotations.

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

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

Single paragraph is dense but front-loaded with purpose. Every sentence provides valuable information. Slightly long but efficient for the complexity.

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

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

No output schema, yet description explains what is returned (summary block, advisory detail, links, versions) and covers ecosystem limitations, performance caveats, and error handling. Thoroughly complete given tool 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 has 100% coverage for 2 parameters. Description adds meaning: 'Specific version to check' for version, 'Defaults to latest published version when omitted' and 'Scoped packages (e.g. @types/node) are accepted' for package. This goes beyond basic 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 starts with a specific verb+resource: 'Composite should I add this npm package to my project check'. It clearly states what the tool does (scans across deps.dev and bundlephobia) and differentiates from siblings by focusing on npm packages and listing returns.

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

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

Explicit when-to-use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also explicitly states when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing 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 annotations (readOnlyHint, idempotentHint), the description reveals the embedding model (BGE-base-en), similarity metric (cosine), window size (500 char), char cap (200K), truncation behavior, and return values (passages with offsets and scores). No contradiction with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core action, then provides usage guidelines, pairing, and technical details. No redundancy; every sentence adds value.

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

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

Despite no output schema, the description fully explains return values (passages, offsets, scores) and constraints (cap, truncation). For a tool with 3 simple params, this covers all necessary context for correct invocation.

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

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

Schema coverage is 100% with clear descriptions. The description adds usage context by specifying that 'text' is already-fetched content and gives example queries, but the schema already conveys the meaning. The extra examples slightly enhance 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 explicitly states it performs semantic search inside a fetched record, using precise verbs and resource examples (SEC 10-K, article). It differentiates from siblings like ask_pipeworx_grounded by noting it saves context and returns passages with offsets, making the purpose unmistakable.

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

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

Provides clear guidance: use when the record is too big for the prompt, and explicitly pairs with ask_pipeworx_grounded for grounding over passages. This gives the agent concrete when-to-use and when-not-to-use context.

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

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

The description goes well beyond annotations, detailing required OAuth account, subscription types with examples, delivery channels (email, SMS, webhook) with limitations (10 SMS/day, webhook auto-disable after 10 failures), and authentication requirements. Annotations only provide idempotentHint and readOnlyHint, but the description adds rich behavioral context.

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

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

The description is well-structured, starting with the core purpose, then listing types and delivery options. Every sentence adds value without redundancy. It is concise given the complexity of the tool.

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

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

Despite no output schema, the description covers the return value (subscription ID), all parameters, constraints, and edge cases (SMS verification, webhook secret). It is self-contained and sufficient 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?

With 100% schema coverage, the description adds significant meaning beyond the schema by providing concrete examples for each subscription type and explaining delivery channel behaviors. It clarifies the format and constraints of parameters like delivery channels.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription ID. It specifies the resource (live-data event stream) and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (for setting up alerts) and provides detailed type-specific parameters and delivery options. It does not explicitly contrast with sibling tools but clearly establishes its own role.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining what the tool returns (category-bucketed example questions) and that it can be called with or without a topic argument.

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 listing multiple trigger phrases and usage details. While it is packed with information, it could be slightly more concise, but it is well-organized and front-loaded with the 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?

Given the tool's role as an onboarding guide, the description fully explains its function, arguments, and use cases. No output schema is needed, and the description provides complete context for the 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% and the schema already describes the optional 'topic' parameter with possible values. The description adds the key insight that omitting the parameter gives a full cross-category spread, which aids correct invocation.

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 an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs like 'returns' and 'use this FIRST' to distinguish it from sibling tools like ask_pipeworx.

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

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

The description explicitly states when to use this tool ('FIRST when you do not yet know what Pipeworx can do' and 'to learn how to call the meta-tools'). It hints at alternatives by mentioning meta-tools but does not explicitly list when not to use it versus siblings.

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

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

Beyond annotations (non-read, non-destructive, idempotent), the description adds ownership enforcement and deactivation vs deletion, which are critical for correct invocation.

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

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

Three sentences, front-loaded with purpose, each adding value. No redundancy or unnecessary words.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership constraint, side effects, and historical data retention completely.

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

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

Schema already documents the single parameter with description. The description only adds 'by id', confirming the parameter's role, but doesn't add significant new meaning.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription by id'. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description implies when to use: to cancel your own subscriptions. It mentions ownership enforcement and the deactivation behavior, but doesn't explicitly exclude alternatives.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive hints, and the description adds significant context beyond them: the SEC/XBRL fast path vs grounded fallback, the verdict enum, and the crucial caveat that could_not_verify carries a verification_error and must not be treated as evidence. This is rich behavioral disclosure.

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 every sentence is targeted: trigger phrases, usage, pipeline, return values, and caller caveats. It is front-loaded with examples and not padded, though slightly verbose for a single-purpose tool.

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

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

With no output schema, the description thoroughly documents return values (six verdicts), the structured vs grounded source paths, and the meaning of each edge case. It even explains why the tool replaces multiple sequential calls, making the overall behavior fully understood.

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

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

Schema coverage is 100% with detailed parameter descriptions, including tolerance_pct's semantics and default. The description adds a bit of context ('exact percent-delta math') but no new parameter-specific details beyond what the schema already provides, 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 specifies the exact job: natural-language claim verification against authoritative sources, with concrete trigger phrases. It clearly distinguishes this tool from general research by focusing on true/false checks and even splits into two pathways (financial vs any other claim).

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 states when to use this tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also gives important usage guidance for interpreting edge verdicts (could_not_verify vs unsupported). However, it doesn't explicitly contrast with sibling tools like deep_research or ask_pipeworx_grounded, so it's not a perfect 5.

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