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?

Adds behavioral context beyond annotations: routes to tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and notes it is 'one fast call' and works on every tier. Also discloses that it routes to live news for breaking-news inquiries, which is not in 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 well-structured and front-loaded with the key message 'PREFER OVER WEB SEARCH'. Each section serves a purpose: sources, trigger phrases/examples, alternatives, and news behavior. Some redundancy in the domain list, but it remains scannable and earns its length.

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

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

Given complexity and no output schema, the description fully covers what the tool does, what it returns, when to use it, and how to escalate to alternatives. It also indicates broad coverage across domains and includes examples of actual queries, making it sufficient for an agent to decide when to invoke.

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

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

Schema coverage is 100% (all aliases for 'question'), so baseline is 3. The description adds meaning by giving concrete example questions and specifying natural-language query syntax, which is not present in the schema beyond the basic field description.

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

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

States clearly it answers factual questions by routing to 5,529 tools across 1,455 sources, and explicitly positions itself as the default entry point. Distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific cases.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, 'USE WHENEVER the user asks...' with trigger phrases. Also states when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions, and clarifies news handling.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context beyond annotations: it discloses that this is an experimental version with candidate routing improvements possibly enabled, states that no candidate is currently active (as of 2026-07-26), and reassures that it is a full working router. 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 three sentences long, front-loads the core purpose ('Beta version of ask_pipeworx'), and each sentence contributes important information: identity, current status, usage guidance, and system assurance. While somewhat dense, it remains readable and avoids 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 that there is no output schema, the description compensates by noting 'same response shape' as ask_pipeworx, which is acceptable because ask_pipeworx is a sibling tool. It covers identity, current experimental status, usage context, and routing behavior. For a simple interface (one required question parameter), this is reasonably complete, though it could have described the response shape more explicitly.

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% — all six parameters (question and its aliases) are fully documented in the input schema. The description mentions 'same arguments' but does not add any new parameter semantics beyond what the schema already provides. Per the rubric, a baseline of 3 is appropriate when schema fully covers parameters.

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

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

The description clearly states that this is a beta version of ask_pipeworx, a universal router with 5,529 tools, and explicitly differentiates it from the stable ask_pipeworx by mentioning 'candidate routing improvements.' This provides a specific verb (ask) and resource (universal router), making the tool's purpose unambiguous and distinct from its sibling.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives clear when-to-use guidance. It also clarifies that 'Falls back to nothing — this IS a full working router,' preventing misuse as a meaningless stub. However, it does not explicitly state when not to use it (e.g., when stability is critical), so it stops short of a 5.

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

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

Goes beyond annotations to describe the return contract ({answer, evidence, confidence, ...}) and refusal modes, adding behavioral context about how answers are grounded and when refusals occur.

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

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

Description is detailed but every sentence serves a purpose: definition, function, return format, use case, tradeoff. Front-loaded with the key differentiator.

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 documents the return shape, error/refusal behavior, and usage conditions, making it complete for an agent to select and invoke.

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% for parameters; description does not add meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly identifies the tool as a grounded, hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx via the 'EXTRACTS the answer using ONLY what the tool result contains' contrast.

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 specifies when to use (when answers will be quoted, cited, or acted on) and when to prefer the alternative (ask_pipeworx for casual lookups), including the cost tradeoff.

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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses rich operational behavior: account and paid-tier requirements, decomposition into facets routed in parallel across 5,529 tools, the findings-packet format (verbatim evidence, confidence, source, fetched_at, citations), gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. It also explains that citations are only included when resolvable, avoiding false expectations. No contradiction with annotations.

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

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

The description is long but densely packed with high-value information: account caveats, alternative routing, depth semantics, citation reliability, and performance expectations. It is well-structured (account first, then core behavior, then use cases, then details) and front-loaded, though the length prevents a perfect conciseness score.

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 covers what the tool returns (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), how depth levels affect behavior, edge cases (unanswerable facets, unresolvable citations), and performance expectations. For a tool this complex, it leaves very little ambiguity.

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 documents both parameters at 100% coverage, but the description adds substantial nuance beyond the schema. It explains depth levels in terms of facet count, hop behavior, gap recovery, and paid tier, and clarifies that the question parameter accepts broad, multi-part input. This goes well beyond the schema 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 defines the tool with a strong verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly states what it is not ('NOT open-web search'). It clearly differentiates from sibling tools by directing single lookups to ask_pipeworx, making its purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even account-tier guidance ('If you are not signed in, use ask_pipeworx'). This is exemplary usage guidance with named 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, 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?

Discloses fanned-out sources, soft-fail for patents after May 2025, and specific return fields. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; 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?

Well-organized with front-loaded examples, but slightly verbose (multiple sentences). Every sentence earns its place, but could be more concise.

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

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

Given complexity (multiple sources, soft-fail, no output schema), description covers return fields, input constraints, and behavioral traits comprehensively.

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

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

Schema coverage is 100% but description adds meaning: explains valid formats (ticker or CIK) and explicitly excludes names, adding 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 uses specific verbs like 'profile' and 'brief me on' with resource 'US public company' and lists data sources (SEC, XBRL, etc.), distinguishing from siblings like resolve_entity and compare_entities.

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

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

Explicitly states when to prefer this tool over chaining single-pack lookups and when not to use it (names not supported, recommends resolve_entity). Provides clear context.

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

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

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?

Annotations indicate read-only, idempotent, open-world; description confirms and adds rich behavioral context: compatibility warnings, temporal alignment, skipped cross types. 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?

Long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Front-loaded with purpose. Slightly verbose but informative.

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

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

Thorough coverage of complex behavior: modes, safety fields, temporal alignment, skipped cross types. Explains response format despite no output schema. Fully adequate for the 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 100% with descriptions; description adds value by explaining modes and context for each parameter. Could be slightly more concise but still adds 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 title and description clearly state the tool computes cross-venue spread between Kalshi and Polymarket. It distinguishes from sibling 'polymarket_arbitrage' by specifying cross-venue focus and detailed mode descriptions.

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 describes TWO MODES (topic vs explicit parameters) and when each to use. Warns that pre-mapped topics often return compatibility warnings, providing clear when-to-use and when-not-to-use guidance.

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

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

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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses detailed behavior: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI unavailable, labeling identifiers with source, and explicitly listing unresolved identifiers as `unresolved`. This significantly exceeds annotation coverage.

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

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

The description is long but every sentence contributes useful information. It is front-loaded with user-facing examples, then a concise purpose statement, followed by structured type details. No fluff or repetition.

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

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

The tool handles two distinct entity types with multiple identifiers and failure modes. The description covers return values implicitly (sources, unresolved list), edge cases (degradation), and internal behavior, making it complete even without an output schema.

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

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

Although schema coverage is 100%, the description adds substantial semantic value: explains the 'type' enum in context, gives concrete examples for 'value' (ticker, CIK, name; brand/generic drug), and describes what each type returns. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with specific examples. It distinguishes itself from siblings by focusing on ID resolution, not profiling or search.

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

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

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains it replaces 2-3 manual lookups. However, it does not explicitly name alternatives or state when not to use it, 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.