Google_ads

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return format details (per-model score, confidence, signals, raw_response + combined view) and clarifies cost model (BYO key for Anthropic). No contradictions.

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

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

Three well-structured sentences: action+output, model details, use cases. No filler, every sentence adds value. Front-loaded with core purpose.

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

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

Despite no output schema, description explains return structure adequately. Covers all 4 parameters, use cases, and behavioral context. Complete for a read-only probing tool with straightforward output.

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

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

Schema description coverage is 100%. Description adds rich context for each parameter: entity examples, model options with default, _apiKey purpose and when required, context disambiguation help. Far exceeds schema 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 clearly states the verb 'probe' and resource 'LLMs for what they know about a business / brand / product / topic' with scoring output. It differentiates from siblings by focusing on brand visibility across models, distinct from general Q&A 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?

Lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides model selection guidance (default vs. BYO key). Lacks explicit when-not-to-use or direct comparison to potentially similar siblings like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it internally routes to thousands of tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. There is no contradiction with the annotations.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), followed by mechanics, trigger phrases, examples, and a final 'START HERE' rule. It is slightly long but every sentence earns its place by providing practical guidance; no filler was found.

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 one required parameter and no output schema, the description explains input styles, data scope, routing behavior, and return format (structured answer with citation URIs). It does not discuss limitations, failure modes, or when to prefer ask_pipeworx_beta or ask_pipeworx_grounded, but given the annotations and schema richness, the description is largely 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?

The input schema fully documents the required 'question' parameter and its five aliases with 100% coverage, so the description is not required to repeat parameter details. It adds examples and the types of questions that are acceptable, but it does not add meaningful parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific behavior: routes a natural-language question to the right one of 5,798 tools across verified sources and returns a structured answer with citation URIs. It is clearly distinguished from web search, but it does not explicitly differentiate itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, leaving some ambiguity about which variant to choose.

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 usage triggers ('what is', 'look up', 'find', 'get the latest', 'current'), concrete examples, and a strong 'START HERE for most questions' and 'PREFER OVER WEB SEARCH' directive. However, it does not mention exclusions or when a sibling tool such as deep_research or ask_pipeworx_grounded would be the better choice, so guidance is not fully complete.

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 safety profile is covered. The description adds valuable context: this is a full working router, not a fallback/stub; candidate routing improvements may be enabled live; the current experimental status and date of last retirement. It clearly explains what beta means behaviorally without contradicting 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 detailed but earns its length by covering the beta distinction, current status, usage instructions, and comparison purpose. It is front-loaded with the core identity ('Beta version of ask_pipeworx') and then efficiently explains behavior. Slightly dense but not wasteful.

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 this is a router tool with no output schema and simple parameters, the description covers the essential context: identical routing behavior, experimental nature, current no-op status, and how results are used. It doesn't need to explain return values heavily since the tool mirrors ask_pipeworx. The only minor gap is not describing the exact response format, but that is inherited from the stable tool and likely known.

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

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

Schema coverage is 100%, with the primary 'question' parameter fully documented and aliases (q, query, prompt, text, input) listed in the schema itself. The description adds no additional parameter semantics beyond what the schema already provides, which aligns with the baseline 3 for high schema coverage.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, explicitly stating it is an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing candidate status. The verb+resource is clear: use this beta router for routing queries to tools.

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

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

The description explicitly tells the agent when to use it: exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. It also clarifies the current state — no candidate active, so it matches ask_pipeworx exactly — which prevents confusion. It names the sibling alternative implicitly and explains the experimental edge.

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

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

The description discloses significant behavioral detail beyond annotations: it only uses tool result content, returns a structured success object with evidence and confidence, and can explicitly refuse with enumerated refusal reasons. It also surfaces the cost tradeoff of one extra LLM call. These behaviors are not conveyed by the readOnly/openWorld/idempotent annotations, so the description adds substantial transparency.

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

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

Every sentence in the description earns its place: core purpose, routing mechanism, success response shape, refusal response shape, use cases, and cost comparison are all packed in without redundancy. The structure is front-loaded with the critical 'hallucination-resistant' identity and flows logically.

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

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

With no output schema, the description fully documents both success and refusal return formats, which is essential for an agent to interpret the result correctly. It also explains when to prefer the sibling, what kinds of questions are appropriate, and the cost consequence, making the description self-sufficient for correct invocation and response handling.

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

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

The input schema has 100% description coverage for the single real parameter, question, including aliases, so the description need not restate parameter syntax. The description does add context about how the question is routed and used, but no additional parameter-specific detail is necessary. Baseline 3 is appropriate because schema carries the load.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific mechanism: it routes a query through 5,798 tools and extracts answers only from the returned data. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, making the purpose and differentiation 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative ask_pipeworx and gives a clear when-not-to-use rule: 'prefer ask_pipeworx for casual lookups,' justified by the extra LLM call cost.

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

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

The description extensively details behavioral traits beyond annotations, including resolution confidence handling, parent event extraction, news fields with fallback mechanisms, safety short-circuits for low-confidence matches, closed market handling, wide-spread warnings, and resolution-rule risk parsing. This far exceeds what the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations convey.

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

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

The description is front-loaded with the main purpose but becomes lengthy with many details and examples. While each section adds value, it could be more concise. Nonetheless, the structure is logical: purpose, usage, behavior, response details, safety notes.

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 3 parameters and no output schema, the description is remarkably complete. It covers resolution logic, fan-out behavior, response shapes, confidence scoring, parent events, news fields, safety mechanisms, and cancellation rules. No significant gaps are apparent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., default depth is thorough, recommend false for include_raw) but does not significantly enrich parameter meaning beyond the schema. The examples clarify input formats but are also present in schema examples.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and resource (Polymarket bet) with concrete examples like 'should I bet on X'. It distinguishes from sibling tools (e.g., polymarket_edges) by focusing on comprehensive data aggregation and evidence packets.

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 usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives conditional instructions, such as inspecting market_match_confidence and parent_event before trusting analysis. Multiple category-specific fan-out examples clarify when which sub-tools are invoked.

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

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

The description adds significant behavioral detail beyond annotations, such as how fiscal year handling works for companies (AAPL Sep, NVDA Jan) and that results are sorted by primary metric. It also explains the data sources and return format (paired data + citation URIs). No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is efficient, front-loading the purpose and trigger phrases. It packs substantial detail into a few sentences without being verbose. Slightly long but justified 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?

Given the absence of an output schema, the description adequately covers return data (paired data + citation URIs) and sorting behavior. It also explains the data sources and entity-specific differences, providing enough context for the agent to understand inputs and outputs.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context: explaining that type='company' pulls financial data and type='drug' pulls adverse event/trial data, and clarifies that values should be tickers/CIKs or drug names with examples. This adds value beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, specifying the exact data pulled (financials from SEC EDGAR/XBRL for companies; FAERS counts, FDA approvals, trial counts for drugs). It also distinguishes itself from siblings like entity_profile by recommending it over sequential single-pack lookups.

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

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

Explicitly provides trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and strong guidance to prefer this tool over sequential lookups. It also clarifies the entity types and what each pulls, helping the agent decide when to use it.

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 readOnly/openWorld/idempotent, and the description adds concrete behavioral details: parallel decomposition across 5,798 tools, return packet fields (gaps[], contradictions[], citation_uri, hop), 'never invented' data, semantic excerpting, and latency expectations. These go well beyond 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 information-dense, with the auth caveat and alternative front-loaded. Minor redundancy (ask_pipeworx mentioned twice, 'Inputs' line duplicating schema) keeps it from a 5.

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

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

Covers auth, exclusions, alternative tool, return format, timing, and edge cases like citation fetchability and contradiction scanning. No output schema exists, so the explicit return-packet description fills the gap 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 coverage is 100% and both parameter descriptions are already detailed, including depth options and the paid thorough tier. The tool description adds little beyond example questions and a default-standard note, so it stays at the 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' Explicitly distinguishes from open-web search and from sibling ask_pipeworx for single lookups, so an agent can select correctly.

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

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

Gives explicit when-to-use conditions: broad/multi-part questions over structured data, and specific alternatives: ask_pipeworx for single lookups or when not signed in. Also flags the paid tier requirement for thorough depth.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds value by detailing return format (top-N tools with schemas, ready to call) and no second lookup needed.

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?

Concise, front-loaded, each sentence adds value: purpose, example domains, return format, usage tip. No wasted words.

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

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

No output schema, but description adequately explains return format: top-N tools with names, descriptions, and full schemas. Sufficient for an agent to understand what it will receive.

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

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

Schema covers 100% of parameters with descriptions. Description mentions query as natural language but adds little beyond 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?

Description clearly states 'Find tools by describing the data or task' with specific verb and resource. It distinguishes itself from sibling tools which are domain-specific; this is a meta-tool for 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 says 'Call this FIRST when you have many tools available' and lists example use cases like SEC filings, FDA drugs, etc., providing clear when-to-use guidance.

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

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

The annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: source fan-out, sources_used/sources_failed semantics, the USPTO soft-fail, FDA expectation caveat, and the private-company resolved:false behavior. There is no contradiction with the annotations.

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

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

The description is dense and somewhat long, and it repeats the name-resolution and type-interchangeability details that already appear in the schema. However, it is front-loaded with examples and the key usage preference, and each added clause carries useful operational 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?

There is no output schema, so the description must explain return shape, and it does: cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers edge cases like empty sections, private companies, and partial source failures, making it fully actionable without further 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 description coverage is 100%, so the schema already documents that type accepts "company" or "ticker" interchangeably and that value can be a ticker, CIK, or company name. The description's examples and repeated interchangeability note are helpful but do not add meaning beyond what the schema already states.

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

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

The description opens with concrete user phrasings and states the precise capability: a single cross-source profile of a US public company. It clearly identifies the resource and scope, and distinguishes itself from chaining individual SEC/XBRL/news lookups.

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

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

It explicitly says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view. It also covers input shaping (ticker, CIK, name) and the expected behavior for private companies, giving the agent clear routing and fallback 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 set destructiveHint=true, so the description does not need to emphasize destructiveness. However, it adds useful context about the types of data to clear (stale, sensitive), which adds value beyond the annotation.

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 sentence states the core function, second provides usage context. No fluff, every word earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose and usage. It includes both what it does and when to use it, making it self-sufficient.

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

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

The only parameter 'key' is already described in the schema as 'Memory key to delete'. The description doesn't add additional semantics beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It also distinguishes from sibling tools like 'remember' and 'recall' which are explicitly mentioned.

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 guidance on when to use this tool: when context is stale, task is done, or to clear sensitive data. It also name-drops related sibling tools to help with tool selection.

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 fully declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is clear. The description adds what metrics are returned but doesn't disclose any additional behavioral traits (e.g., data aggregation level, pagination, rate limits). With annotations covering safety, a score of 3 is appropriate.

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, no fluff. It efficiently states the purpose, what's returned, and a use case. Every sentence adds value.

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

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

Given that an output schema exists, the description need not explain return values in detail. It covers the core purpose and typical use cases. For a read-only metrics tool with good annotations and complete schema, this is sufficient.

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

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

All 5 parameters have descriptions in the input schema, so schema coverage is 100%. The description does not add new detail beyond what the schema already provides (e.g., date format, optional filters). Baseline 3 is correct when the schema carries the load.

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

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

The description clearly states the tool returns performance metrics for campaigns over a date range, including specific KPIs (impressions, clicks, etc.). This distinguishes it from siblings like gads_list_campaigns which returns a campaign list without metrics, and gads_get_campaign which returns a single campaign's details.

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 'Use to analyze campaign effectiveness or compare performance trends,' which provides context but no explicit guidance on when not to use it or alternatives. For example, if the user needs raw data or a search, gads_search might be more appropriate. Sibling tools are not mentioned.

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 no extra behavioral context beyond its basic function. It 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?

Two sentences efficiently convey the action, returned data, and use case. No extraneous information.

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

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

For a simple read tool with annotations and output schema present, the description covers purpose, usage, and key return fields. It is sufficient for an AI agent to understand and invoke the tool correctly.

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

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

Input schema has 100% description coverage for both parameters. The description does not add new meaning beyond the schema; it simply reinforces that the tool gets settings for a campaign, which implies the campaign_id parameter.

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

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

The description clearly states the verb 'Get', the resource 'specific campaign', and lists returned fields (name, status, budget, etc.). It distinguishes from siblings like 'gads_list_campaigns' and 'gads_campaign_metrics' by focusing on detailed settings of a single campaign.

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 'Use to review or audit a campaign's current setup', providing clear guidance. However, it does not mention when not to use this tool or suggest alternatives (e.g., using gads_campaign_metrics for metrics, or gads_list_campaigns for listing).

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, destructiveHint, providing safety context. The description adds value by specifying what data is returned (ad group names, IDs, statuses, CPC bids) and the intended use cases, which helps the agent understand the behavior beyond 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 two sentences, front-loading the action and quickly covering what is returned and when to use it. Every sentence contributes value without redundancy.

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

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

Given the tool's simplicity (4 parameters, read-only, output schema exists), the description covers the essential aspects: purpose, key parameters, returned fields, and use cases. It does not discuss pagination or default limit details, but that is a minor gap for a listing operation.

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

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

Schema coverage is 100%, so the input schema already describes all four parameters well. The description mentions filtering by campaign ID (campaign_id) but does not add significant extra meaning beyond the schema. It does not clarify the limit default or status options, which are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (list ad groups), the resource (within a campaign), and the unique identifier (campaign ID). It lists returned fields (names, IDs, statuses, CPC bids) and provides a use case (explore campaign structure or select an ad group), distinguishing it from sibling tools like gads_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?

The description includes a usage statement ('Use to explore campaign structure or select an ad group for analysis') which implies when to use, but does not explicitly mention when not to use or provide direct comparisons to alternative tools. The context of sibling tools helps, but the description lacks explicit 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, and destructiveHint=false, so the description is not burdened with safety disclosure. It adds value by specifying the fields returned (names, IDs, statuses, budgets, types). No contradictions with annotations. However, it could mention pagination or performance implications for large accounts.

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 verb 'List'. Every sentence adds value: first states purpose and return data, second gives usage guidance. No wasted words.

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

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

Given the presence of an output schema and robust annotations, the description is complete. It covers the tool's purpose, return values, and a common use case. The parameter count (3, 1 required) is moderate and well-addressed by the 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?

Schema coverage is 100% with descriptions for all three parameters. The description does not add meaning beyond the schema (e.g., does not explain limit default behavior or customer_id format). Baseline 3 is appropriate as the schema already provides the necessary semantics.

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 all campaigns' with a specific verb and resource. It lists the return fields (names, IDs, statuses, budgets, types) and provides a use case: overview account structure or find a campaign ID. This effectively distinguishes it from sibling tools like gads_campaign_metrics or gads_get_campaign.

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 usage context: 'Use to overview account structure or find a campaign ID for detailed analysis.' While it does not mention when not to use or directly compare to siblings, the guidance is clear and actionable. The context signals and sibling list further aid 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description need not repeat these. The description adds no behavioral traits beyond annotations, but does not contradict them. A score of 3 is appropriate as the description adds marginal 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 two sentences: one for the core action, one for usage context. It is front-loaded, concise, and contains no redundant information. Every sentence adds value.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers usage context. It could mention return format or limitations, but completeness is high for a tool with strong structured metadata.

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

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

Schema coverage is 100%, with both parameters documented. The description adds examples of filtering and aggregation, providing context beyond schema but not essential new semantics. Baseline 3 is justified as the schema does the primary work.

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

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

The description clearly states the tool runs custom GAQL queries against Google Ads data, using specific verbs and resource. It distinguishes from sibling tools like gads_campaign_metrics by emphasizing advanced analysis and custom dimensions, making the purpose unambiguous.

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

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

The description provides clear context for usage using 'Use for advanced analysis' and examples, but does not explicitly state when not to use this tool versus alternatives like gads_campaign_metrics or gads_list_campaigns. The guidance is adequate but lacks exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown format. This explains behavior beyond annotations, though it doesn't cover edge cases like rate limits or error handling.

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

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

The description is two sentences, front-loaded with the core purpose and output, followed by use cases. Every sentence conveys essential information without redundancy. No wasted words.

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

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

Given the low complexity (2 parameters, no output schema, no nested objects) and rich annotations (readOnly, openWorld, idempotent), the description fully covers what the tool does, its inputs, output format, and typical use cases. No gaps are apparent.

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

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

Schema description coverage is 100%, so the schema already defines both parameters (url and max_links). The description reinforces the URL parameter but adds no new semantic meaning beyond what the schema provides. For max_links, the schema already includes default and max values; description does not elaborate. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes itself from sibling tools, which cover unrelated topics like ads (gads*), research (deep_research), and arbitration (polymarket*), making its purpose unique.

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: getting a client's site indexed, drafting for own project, or auditing competitor. It implies when to use (for indexing) but does not specify when not to use or name alternative tools, though no sibling tool overlaps in functionality. Lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields (id, type, etc.) and scopes to 'the caller's subscriptions.' No contradictions.

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

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

Two sentences, first explains purpose and output, second gives usage guidance. No filler, front-loaded with key information.

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

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

For a simple list tool with one optional parameter, all aspects are covered: purpose, return fields, usage context, and safety. No output schema is needed since return fields are described.

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

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

Schema coverage is 100% with the parameter include_inactive fully described. The description does not add parameter-level details, but baseline is 3 due to high coverage.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by implying this is for reviewing existing subscriptions.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool versus alternatives (subscribe, unsubscribe).

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

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

Annotations provide no safety hints (all false), so the description must carry the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and scope constraints ('ONLY for tools served by this Pipeworx connection'), far beyond what structured fields provide.

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

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

The description is a single dense paragraph but every sentence adds necessary information: purpose, usage triggers, exclusion, best practices, token mechanism, rate limits, and quota. Though not bulleted, it's efficiently written and front-loaded with the core purpose.

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

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

Given 4 parameters, nested objects, and no output schema, the description covers all needed aspects: what the tool does, when to use, what to avoid, the claim_token response flow, and rate limiting. It even tells the team's review cadence. Nothing critical is omitted.

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 documents each parameter with descriptions. The description adds extra semantics by explaining how to use `claim_token` and advising not to paste end-user prompts, enriching the `message` field. Baseline 3 plus added value justifies 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly defining the action and target. It distinguishes from sibling tools (all research/monitoring tools) by specifying it's for feedback to the team.

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 scenarios (bug, feature/data_gap, praise) and gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: data derived from CF analytics-engine, no PII, caching (5min-1h). This goes beyond annotations to inform the agent about data source, privacy, and staleness.

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 4 sentences, front-loaded with the core purpose, then use cases, then technical details. No wasted words; every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, use cases, data origin, privacy, and caching thoroughly. It is fully adequate for the agent to understand and use the tool correctly.

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

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

Schema coverage is 100% and the schema description already explains the window parameter (enum values and semantics of short vs long windows). The description reiterates the windows but adds no new parameter meaning beyond what the schema provides.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, using a specific verb 'returns'. It distinguishes itself from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing on trending usage rather than general discovery or Q&A.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, seeing alignment). While it doesn't state when not to use or directly name alternatives, the use cases are clear and helpful for decision-making.

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

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

Beyond the safe annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: monotonicity violations, partition checks, semantic anchor, partition filter, and fill check with realizable edge warnings. 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 thorough but somewhat lengthy, including detailed mechanism and response structure. However, it front-loads the purpose and key modes. Could be slightly more concise without losing critical details, but the complexity justifies length.

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

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

Despite no output schema, the description comprehensively covers response fields (opportunities[], partition_check, fill check) and edge cases (skipped_low_similarity, placeholders_filtered). Complete context for a complex tool with multiple modes.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: it clarifies mutual exclusivity of event and topic, gives example values, and explains what each mode does in detail. This fully compensates for any schema brevity.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (trending, event, topic). This differentiates it from sibling tools like polymarket_edges and polymarket_edge_tracker.

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

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

The description explicitly specifies when to use each mode: no args for trending, event for a specific market slug, topic for cross-event scanning. It also explains why cross-event mode can catch patterns that single-event misses, and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: caching policy (KV-level 1h cache), three response segments, diagnostics, Fed notes, and detailed explanations of edge calculation, slippage, and Kelly sizing. 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 lengthy but highly informative, with front-loaded purpose and detailed inline explanations. Every sentence adds value, though a more structured format (e.g., bullet points) could improve readability without losing 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?

Despite having no output schema, the description comprehensively explains the response structure (by_segment, fed_candidates, _diagnostics) and the reasoning behind Fed exclusions. All 9 parameters are covered with usage context, making the tool fully understandable for an 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 description coverage is 100%, so baseline is 3. The description adds significant extra context beyond schema, such as explaining how min_partition_leg_kelly interacts with partition arbs, and providing usage tips for slippage_pp. This justifies a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It includes the specific use case 'what should I bet on today' and distinguishes the tool from siblings by its unique model families and focus on Pipeworx disagreement.

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 context for when to use the tool ('what should I bet on today') and gives detailed usage tips for parameters (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly state when not to use the tool or compare to sibling tools for exclusion.

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

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

The description extensively discloses behavior: it computes trend and decay, explains negative values, details expired opportunities, and notes snapshot writing conditions and TTL. This goes well beyond the annotations (readOnlyHint, idempotentHint, etc.), providing clear operational expectations.

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

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

The description is detailed but efficiently structured, starting with a core question then expanding. The use of sub-sections (tracked[], expired[], snapshot_dates[]) is clear. A minor redundancy exists (explaining both in text and parentheses), but overall it is well-organized and not overly verbose.

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

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

Given no output schema, the description fully explains the response structure and fields, including meanings of trend values and decay calculation. It also notes limitations like TTL and snapshot gaps. This provides complete guidance for an agent to use the tool effectively.

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

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

The input schema already describes both parameters (days, window) with defaults. The description adds value by specifying clamp ranges (2-30 days), default values (14, '1wk'), and the meaning of the window parameter ('snapshot family'). It also explains how days affects history depth.

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 providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?'), distinguishing it from sibling tools like polymarket_edges which likely provide current edge 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?

The description explains when to use this tool—analyzing edge longevity and decay—and gives context that a 3-week-old wide edge is different from a fresh one. It mentions limits (60-day TTL, snapshot availability) but does not explicitly specify when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, covering safety. The description adds context about it being a check (not executing trades), walking the ladder, returning verdicts, and the risk of partial fills. 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: purpose statement first, then REQUIRES clause, then separate sections for single-market and basket modes, ending with usage guideline. Every sentence adds value; no redundancy. Front-loaded with key 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?

The description covers both modes, return fields (e.g., top_of_book, vwap_fill_price, verdict), and critical warnings about partial fills. While lacking a precise output schema, it provides enough context for an agent to understand expected outputs. Slightly verbose but complete for a safety-check tool.

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

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

Schema coverage is 100% with descriptions. The description adds significant value: explains default behaviors (e.g., side auto default in basket mode), interpretation of size_usd (max spend on buys, target proceeds on sells; for basket, settlement notional), and clarifies the REQUIRES condition.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, each with specific return values. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk.

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

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

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'. Explains why: theoretical overround on thin books is not capturable, and partial basket fills convert arb into unhedged directional position.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing matching limitations, compatibility codes, temporal alignment semantics, unclassified-leg exclusion, skipped comparison counters, and the gross-not-net fee caveat. It also clarifies that a null temporal alignment means unknown, not aligned. No contradiction with annotations exists.

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

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

The description is long but well-structured and front-loaded: core concept, modes, response, safety fields, then caveats. Some points are repeated, such as temporal-alignment ambiguity and both modes sharing the same matcher, so it is not maximally concise. The density is largely justified by the absence of an output schema.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains response contents, safety fields, per-entry flags, fee treatment, skipped comparisons, and edge cases. An agent has sufficient information to call the tool correctly and interpret its results.

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

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

The schema already documents all three parameters with 100% coverage. The description adds value by explaining that the topic parameter auto-fetches the matching event on each venue, that explicit parameters override the topic-mapped side, and that both modes run the same token-overlap matcher.

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 resource (cross-venue spread between Kalshi and Polymarket) and the core task: comparing how the two venues price the same resolving question. It also explains two operation modes. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, leaving that distinction implicit.

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 mode-selection guidance: use topic shortcuts for pre-mapped events and explicit ticker/slug for custom pairings. It also cautions that most pre-mapped topics return compatibility_warning today and that pre-mapped does not mean tradeable. It does not explicitly compare itself with alternative sibling tools, so the when-not/alternative guidance is only partially complete.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by explaining the retrieval mechanism, listing behavior when key omitted, scoping, and pairing with siblings. No contradictions.

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

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

The description is concise with three sentences. It front-loads the main action and efficiently adds context and pairing instructions. No redundant 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?

Given the tool has only one optional parameter and no output schema, the description covers all necessary aspects: purpose, usage, behavior, scoping, and relationship to siblings. It is complete without being verbose.

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 the single parameter 'key' with description and examples. The tool description adds clarity by explaining the behavior when the key is omitted (list all keys), which is not fully captured in the schema. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: retrieve a value by key or list all keys when omitted. It specifies the verb (retrieve/list), resource (saved values), and context (previously saved via remember). It distinguishes itself from siblings remember and forget.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also notes scoping by identifier. However, it does not explicitly state when not to use it or mention alternatives beyond remember/forget.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds key behavioral details: it can mark events as read (mark_read parameter), affecting subsequent calls. This does not contradict annotations but adds useful nuance.

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 compact paragraph with clear front-loading of purpose, followed by parameter details, side effects, and alternative access. Every sentence adds value 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?

The description fully explains the return value (source, citation_uri, raw event payload) and the effect of key parameters. It also addresses polling and alternative access. Without an output schema, this is sufficient for an AI agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions. The description adds examples (e.g., filter by type 'sec_8k') and explains the effect of mark_read, which is beyond the schema. However, it does not elaborate on 'unread_only' or 'limit' beyond what the schema provides.

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

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

The description clearly states the verb 'pull' and the resource 'fired events from your subscription feed.' It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on retrieving alert events rather than managing 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 mentions polling works fine and points to an alternative HTTP endpoint for scripts/dashboards, giving context on usage. However, it does not explicitly exclude when not to use this tool or contrast it with other sibling tools like recell or recent_changes.

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 behavioral context: it fans out to multiple sources, has a specific fallback (GDELT→GNews), soft-fails for USPTO, and returns structured changes with citation URIs.

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

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

The description is relatively concise for its breadth, but it packs many details into a single paragraph. Minor structure improvements could enhance readability, but overall it's 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?

Given the tool's complexity (multiple data sources, date formats, fallback, return structure) and no output schema, the description provides complete context: it lists sources, explains fallback, describes return format, and notes the USPTO limitation.

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%. The description reinforces parameter meaning with examples (e.g., ISO date vs relative shorthand, ticker vs CIK) and usage recommendations (e.g., '30d' or '1m' for typical monitoring).

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: providing a change feed for a company with recent filings, news, and patents. It uses clear verb phrases like 'What's new with X' and distinguishes from the sibling tool 'entity_profile'.

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

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

The description gives clear when-to-use guidance (for time-windowed recent changes) and when-not-to-use (use entity_profile for static profiles regardless of window). It also explains fallback behavior for news sources.

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 write, idempotent, non-destructive. The description adds key details: scoped by identifier, persistence duration (24h for anonymous), and that it's a key-value store. Could mention overwrite behavior more explicitly, but overall adds value beyond annotations.

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

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

Several sentences but each adds value: purpose, usage cues, technical details, and sibling references. Front-loaded with primary purpose. No fluff, but slightly longer than minimal.

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 simplicity (2 string params, no output schema), the description covers everything an agent needs: what, when, how, scope, persistence, and related tools.

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

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

Schema already covers both parameters with descriptions. The description adds practical examples for key naming conventions (e.g., 'subject_property') and value content, which helps the agent choose appropriate values.

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 later, with concrete examples (ticker, address, preference). It distinguishes from sibling tools recall and forget by naming them and explaining the memory lifecycle.

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 ('when you discover something worth carrying forward') and mentions alternatives (recall, forget). Also specifies scope differences between authenticated and anonymous sessions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real behavior: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI fail, explicit `unresolved` fields instead of silent omission, and source-labelled identifiers. No statement contradicts 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 a long, densely parenthetical wall of text that front-loads purpose but buries details inside run-on sentences. Most content is valuable, but repeated query examples and heavy nesting make it harder to parse than a bulleted or shorter version.

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

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

With no output schema, the description carries the burden of return semantics and largely meets it: it names the outputs (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand), explains ownership resolution, and specifies failure/ambiguity behavior (`unresolved`, `figi_candidates`). It is complete enough for an agent to know what it will receive.

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?

Even with 100% schema coverage, the description expands parameter meaning: company values may be ticker, CIK, ISIN, or name; non-ticker instruments like bonds still resolve; ambiguous names return candidates; and the drug path yields RxCUI + ingredient + brand. It also reinforces the critical 'ENTITY NAME ONLY' constraint from the schema.

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

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

The description states a specific action—resolving a user-spoken name to canonical/official identifiers—and backs it with concrete query examples for ticker/CIK/LEI/RxCUI. It distinguishes itself from related tools like entity_profile and compare_entities by framing the output as the IDs that other tools require as input, and enumerates supported types ('company', 'drug').

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 trigger guidance: 'Use FIRST whenever you have a name but need an ID,' plus example questions that should route here. It does not name alternative sibling tools or give a clear when-not-to-use condition, though the ambiguity rule (return figi_candidates rather than asserting) is a useful guardrail.

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, open-world behavior. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. No contradictions with annotations.

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

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

Two sentences, each earning its place: first states purpose, second details process and utility. No redundant words. Front-loaded with key action.

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

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

Description covers purpose, process, output format, and use case. Since no output schema exists, it adequately describes the return structure (ranked list with metrics). Could mention edge cases like entity count limits, but schema constraints may handle that.

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

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

All parameters have schema descriptions (100% coverage). Description adds context beyond schema: 'First entry treated as the subject for narrative; rest are competitors' enhances understanding of 'entities' parameter. Also explains the role of 'models' and 'context' 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?

Description explicitly states 'Compare AI visibility across multiple entities side-by-side' with specific verb and resource. Clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely more general).

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 a concrete use case: 'competitive AI-marketing audits' with example question. Implicitly suggests when to use this over ai_visibility_check by mentioning it probes multiple entities, but doesn't explicitly state when not to use or list 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 goes beyond annotations by detailing the fan-out behavior, partial failure handling, and measurement delays. It adds context about sources_failed and return format, which annotations don't cover. 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 comprehensive but slightly long. However, every sentence serves a purpose, and the most important info is front-loaded. Minor deduction for verbosity.

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

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

Given the lack of output schema, the description fully specifies the return fields, behavioral constraints, and ecosystem limitations. It addresses all likely agent questions about usage and outcomes.

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

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

Schema coverage is 100%, and the description adds value by mentioning scoped packages and default version behavior. It also clarifies the return summary block fields, enhancing understanding beyond the schema.

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

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

The description clearly states it's a composite check for npm packages, specifying the resources (deps.dev, bundlephobia) and the types of queries it answers (safety, popularity, size). It distinguishes from sibling tools by focusing on package dependency scanning.

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

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

The description explicitly says 'Use whenever an agent asks...' and provides clear context for when to use, alternative ecosystems, and graceful degradation. It also warns about potential timeouts for bundlephobia.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flag), and return fields (offsets and similarity scores). 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?

Three sentences, well-structured, front-loaded with purpose. Every sentence adds necessary context 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 no output schema, the description explains return format (top-N passages with offsets and similarity scores). Covers input constraints, pairing info, and limits. Complete for a 3-parameter tool.

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

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

Schema coverage is 100% but description adds value: for 'text' specifies max ~200K chars, for 'query' gives concrete examples, for 'limit' notes default 5 and range 1-20. Also mentions truncation behavior for long inputs.

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

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

The description states it performs semantic search inside a fetched record, using specific verbs like 'search inside', 'pass the text', and 'get back passages'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative tool (ask_pipeworx_grounded). Implies when not to use by the condition of record size.

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 significant behavioral details beyond annotations: OAuth requirement, SMS cap (10/day), phone verification, webhook auto-disable after 10 failures, HMAC signing. 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?

Packed with useful info, front-loaded with main purpose. Slightly lengthy but each sentence adds value. Could benefit from more structured layout (e.g., bullet points).

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?

Covers creation process, account requirement, types, delivery details, and limitations. Missing explicit return structure beyond 'new subscription id' (e.g., webhook_secret). Still fairly complete for a creation tool.

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

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

Schema coverage is 100%, but description enriches with concrete examples for each type's params and detailed delivery constraints (phone verification, SMS cap, webhook HMAC). Adds meaning 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource, distinct from siblings like unsubscribe 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?

Provides clear context: requires Pipeworx OAuth account, lists supported types with examples, delivery channels. Does not explicitly exclude alternatives, but purpose is clear enough for selection.

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

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

Annotations already provide safety hints (readOnly, openWorld, idempotent). Description adds useful context: it returns category-bucketed questions with exact tool+argument shapes, and that it can be called with no arguments or with a topic. 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 somewhat long but efficiently packed with information. It is front-loaded with the purpose and usage guidelines, and every sentence adds value. Could be slightly more concise.

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

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

Given the tool's role as an onboarding tool with many categories and no output schema, the description provides comprehensive coverage: lists categories, explains return format, and indicates first-use scenario. Fully sufficient for an agent to understand when and how 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% with a clear description of the 'topic' parameter. The description provides additional context on possible values and behavior when omitted (full spread vs focused). Adds meaning 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 is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and distinguishes from siblings by being the first tool to use when unsure of Pipeworx capabilities.

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 FIRST when you do not yet know what Pipeworx can do'. Also explains how to use the optional topic parameter for focus, and mentions it reveals how to call meta-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?

Adds behavioral context beyond annotations: row is deactivated (not deleted) and historical events remain available via recent_alerts. 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?

Three concise sentences, front-loaded with 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?

Complete for a simple tool with one parameter and no output schema. Covers ownership, behavior, and historical data implications.

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 adequate parameter description. Description does not add extra meaning beyond what the schema provides, so baseline score 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?

Clear verb 'Cancel a subscription by id' specifies action and resource. Distinguishes from siblings 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on valid use cases. Does not explicitly mention alternatives but context is clear.

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

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

The description provides extensive behavioral context beyond the annotations: it explains the routing logic, the meaning of each verdict, and critically warns that 'could_not_verify means the check did not happen... must not be shown as one.' It also discloses that the tool returns evidence with citations and reasoning, which the annotations do not convey. 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 well-structured and front-loaded with natural-language triggers. Every section serves a purpose: usage, routing, output format, and important caveats. It uses clear labels ('IMPORTANT for callers') to highlight critical behavioral notes, and there is no redundant or fluff 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?

There is no output schema, so the description must fully specify return values, and it does: it lists the verdicts, the 'grounded or structured actual value with pipeworx:// citation,' and reasoning. It also covers edge-case semantics (unsupported vs. could_not_verify) and the two routing paths, leaving no significant gaps for an agent to invoke the tool correctly.

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

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

The input schema covers all parameters with detailed descriptions, so baseline is 3. The description adds a few illustrative examples (e.g., 'Apple's FY2024 revenue was $400 billion') and mentions 'exact percent-delta math,' but it does not significantly enrich parameter semantics 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 defines the tool as 'natural-language claim verification against authoritative sources' and specifies its scope (fact-checking user statements). It distinguishes itself by describing the two processing paths (SEC EDGAR for company financials, grounded pipeline for other claims) and the output verdicts, which differentiates it from sibling tools like ask_pipeworx_grounded or deep_research.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides usage nuance by differentiating financial claims from other factual claims and mentions it replaces multiple sequential calls. However, it does not explicitly state when not to use it or point to alternative tools, so it falls short of a 5.

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