Google_analytics

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

Annotations already declare readOnly/openWorld/idempotent hints, so the safety profile is covered. The description adds valuable behavioral context: the free default model (Workers AI Llama-3.3-70b), that passing _apiKey for Anthropic involves direct costs to the user, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is especially helpful given there is no output schema.

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

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

The description is three sentences, front-loaded with the core function and outcome. The second sentence covers model selection and cost implications, and the third provides return format and use cases. Every sentence earns its place, with no redundancy or filler.

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

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

For a tool with 4 parameters (1 required), good annotations, and no output schema, the description is complete. It covers purpose, parameter behavior, return format, cost implications, and use cases. The lack of an output schema is compensated by the explicit return structure described. There are no obvious gaps that would prevent correct selection or invocation.

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

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

The schema has 100% parameter coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining the default model (free) and the _apiKey behavior (BYO key, direct Anthropic billing), which clarifies the models parameter and the _apiKey's purpose more fully than the schema descriptions alone.

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

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

The description uses a specific verb 'Probe' and clearly identifies the resource as 'one or more LLMs' for scoring visibility of a business/brand/product/topic. It distinguishes itself from sibling tools by focusing on per-model visibility scores (0-100) with confidence and signals, which is a unique function compared to ask/search 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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model behavior and how to enable Anthropic with a _apiKey. It does not name alternative tools or state when not to use it, but the context is clear enough for an agent to decide.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context by revealing that it routes to 5,462 tools, fills arguments, returns stable citation URIs, and works on every tier in one fast call. It does not mention failure modes or rate limits, but the covered aspects align well with annotations and add meaningful behavioral detail.

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

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

The description is longer than average but well-structured: it front-loads the key comparison with web search, then lists use cases, trigger phrases, examples, and alternatives. Every sentence serves a purpose, though it could be trimmed slightly without losing value. The use of uppercase headings and bullets-like structure aids scanning.

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

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

Given the tool's complexity (routing across thousands of tools) and the absence of an output schema, the description is remarkably complete. It explains what the tool does, when to use it, provides concrete examples, mentions the return format (structured answer with citation URIs), and gives performance expectations (one fast call, every tier). No critical information is missing for an agent to select and invoke it effectively.

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

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

Schema coverage is 100% with the question parameter and five aliases fully documented. The description does not add meaning beyond the schema; it repeats the natural-language concept and gives examples, but the schema already provides examples and alias descriptions. The baseline of 3 is appropriate since the schema carries the parameter information.

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

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

The description clearly states that ask_pipeworx routes factual questions to specialized tools and returns structured answers with citations, which distinguishes it from web search and sibling tools. It explicitly names alternatives (ask_pipeworx_grounded, deep_research) and positions itself as the default entry point, making its role and scope unmistakable.

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

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

The description gives explicit when-to-use guidance: prefer over web search for authoritative data, use whenever the user asks 'what is', 'look up', etc. It also provides when-not-to-use instructions by directing users to step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad questions. This is exemplary usage 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it is an experimental edge with candidate routing enabled live only when under test, currently inactive, and 'falls back to nothing' (i.e., it is a full working router, not a degraded fallback). This goes beyond the annotations without contradicting them.

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

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

The description is four sentences, each contributing unique information: beta status, current inactive candidate, usage instruction, and operational guarantee. It is front-loaded with the key purpose. Slightly verbose but efficient overall.

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

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

Given the tool's complexity (a router over 5,462 tools) and lack of output schema, the description adequately covers the tool's behavior, current state, and usage. It references 'same response shape' to point to the stable ask_pipeworx for format details, which is sufficient for an agent familiar with the sibling. It does not enumerate the 5,462 tools, but that would be impractical and unnecessary here.

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 all six parameters documented as aliases for 'question'. The description mentions 'same arguments' but does not add further param semantics. Since the schema fully covers parameter meaning, the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools and response shape. It distinguishes itself from the stable ask_pipeworx by noting it has candidate routing improvements. This is a specific verb+resource statement that differentiates from siblings.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the experimental nature and that results are compared against the stable router, implicitly warning against use when stability is required. This is strong guidance beyond just a general description.

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 key behavioral traits beyond the annotations, such as the extra LLM call cost, the refusal mechanism with specific refusal reasons, and the guarantee that answers are extracted only from tool results. This aligns with the readOnlyHint and idempotentHint annotations, adding value about failure modes and side effects.

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

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

The description is dense but not overly verbose; each sentence adds critical information (what it does, returns, refusal reasons, use cases, cost trade-off). It is structured with front-loaded purpose, though slightly long due to the detailed refusal specification. It earns a 4 rather than 5 due to minor redundancy in listing refusal reasons in both the return format and use case clause.

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 absence of an output schema, the description thoroughly explains return values (success and refusal shapes) and covers use cases. It addresses accuracy guarantees, cost, and behavioral context, making it complete for an agent to select and trust the tool appropriately.

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% since all six parameters are documented as aliases for 'question.' The description does not add new meaning beyond the schema; it merely confirms natural language input. A score of 3 is the baseline for high schema coverage with no additional parameter details.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by specifying it extracts answers strictly from tool results and returns explicit refusals, making its purpose unmistakable.

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

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

The description provides explicit usage criteria: use when answers will be quoted, cited, or acted on, and when the agent must not invent facts. It also gives concrete examples (financial verdicts, legal claims) and advises preferring ask_pipeworx for casual lookups, offering clear guidance between alternatives.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond by detailing the resolver contract (match confidence, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), resolution-rule risk (cancellation_rule), and data source fallback behavior (GDELT 429, GNews backfill). This is an exemplary disclosure of behavioral traits.

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

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

The description is extremely long, but it is well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with a one-sentence summary. The length is justified by the tool's complexity, though some redundancy (e.g., repeated market status explanations) could be trimmed.

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

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

With no output schema, the description must fully explain return values and behavioral edge cases. It does this comprehensively: result.market/analysis/evidence shapes, resolver contract, parent-event extraction, news fallback fields, safety short-circuits, and cancellation-rule risk. This covers all critical aspects an agent needs to interpret and trust the results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing multiple concrete examples for the 'market' parameter (slug, URL, question text) and explaining the semantic trade-offs of 'depth' and 'include_raw' (quick vs thorough fan-out, payload size implications). This goes beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data') and immediately clarifies input formats (slug/URL/question text). This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on market-wide edge detection rather than per-bet data 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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples for different bet types. However, it does not explicitly mention when not to use it or compare to alternatives, so it misses the full 5-point criterion.

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, and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral details beyond the annotations: it authenticates fiscal-year handling ('off-calendar fiscal years handled correctly — AAPL Sep, NVDA Jan'), explains sorting ('Results sorted by primary metric'), and describes the return shape ('Returns paired data + pipeworx:// citation URIs per entity'). This goes well beyond what the 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 dense but efficient. It front-loads the trigger phrases and core purpose, then breaks into type-specific details. Every sentence adds value, from the fiscal-year handling note to the sorting behavior. It is a bit long, but for a tool that handles two entity types with distinct data sources, the length is justified. No redundancy that wastes the reader's time.

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 needs to convey return values, and it does: 'Returns paired data + pipeworx:// citation URIs per entity.' It also explains data sources, entity count limits, sorting, and the efficiency gain. The only minor gap is that 'primary metric' is not explicitly defined per type (e.g., revenue for companies, adverse-event count for drugs), which could cause ambiguity for some queries. Overall, it is highly complete for the tool's read-only nature.

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

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

The schema already covers both parameters with descriptions and enums, reaching 100% coverage. However, the description adds meaningful context by explaining what data each type retrieves (10-K revenue/net income/cash/debt vs. FAERS/adverse-event/trial counts) and giving concrete examples (['AAPL','MSFT'], ['ozempic','mounjaro']). It clarifies the 2–5 range in plain language. While the schema does the heavy lifting, the description enriches param meaning enough to deserve above baseline.

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

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

The description opens with clear natural-language triggers ('Compare X and Y', 'X vs Y', 'rank these companies') and then states the core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It explicitly distinguishes itself from alternatives by saying 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups,' which clearly separates it from sibling tools like 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 provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete query examples that should trigger this tool, and explains the difference between type='company' (10-K financial data) and type='drug' (FAERS/approval/trial data) so the agent knows which type to choose. This is strong usage direction.

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?

Despite readOnlyHint=true and destructiveHint=false annotations, the description adds extensive behavioral detail: account requirements, parallel decomposition across 5,462 tools, return format, citation policy (canonical pipeworx:// URIs only when fetchable), gap handling, hop behavior, semantic excerpting, and latency expectations. This far exceeds annotation coverage.

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

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

The description is long but information-dense, and front-loads the most critical caveat (account required). Sentences earn their place with specific numbers, examples, and alternatives. Slightly overlong but justifiable given the tool's complexity.

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

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

For a complex research tool with only 2 well-documented params and no output schema, the description is remarkably complete: it explains the return packet, gaps[], contradictions[], citations, hops, latency, and sibling differentiation. Covers both operational prerequisites and behavioral expectations.

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

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

Schema coverage is 100% and already describes both parameters well. The description adds practical nuance about depth values (e.g., 'thorough needs a paid plan', 'standard re-angles unanswered gaps'), which complements the schema but doesn't add syntax or format details beyond it. 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 performs grounded multi-source research across Pipeworx's structured data sources in one call, distinguishing it from open-web search and single-lookup tools. It gives specific verb-resource (research over 1,419 structured data sources), scope, and explicit contrast with siblings like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data; for single lookups or breaking/current-news topics use ask_pipeworx instead. It also explains the depth tiers and when each is appropriate, giving clear context and 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, idempotentHint, and destructiveHint, so safety profile is covered. The description adds value by explaining the return output (top-N tools with full schemas, no second lookup needed) and the 'ready to call directly' property. It doesn't discuss edge cases like no matches, but that's acceptable given the annotations.

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

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

The description is well-structured with a clear opening, a domain list, return behavior, and usage directive. It is slightly long due to the domain enumeration, but each sentence serves a purpose and the structure is logical.

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 discovery tool with one required parameter and high schema coverage, the description covers purpose, usage, return format, and positioning relative to siblings. No output schema exists, but the description sufficiently explains what the agent will receive. This is complete for the tool's complexity.

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

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

The schema description coverage is 100%, with every parameter documented including aliases. The description only paraphrases the query concept and references 'top-N' (limit). It adds no meaningful semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a meta-search over other tools ('Find tools by describing the data or task'), listing specific domains and distinguishing itself from siblings by being the 'discover' tool. It explicitly tells the agent to call it first when many tools are available, which sets it apart from domain-specific siblings.

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

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

The description specifies when to use it ('browse, search, look up, or discover what tools exist'), provides concrete examples, and gives the key directive 'Call this FIRST when you have many tools available and want to see the option set'. This is strong guidance 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 (readOnlyHint, idempotentHint, etc.) are complemented by rich behavioral detail: fan-out across sources, return structure, patent API sunset and soft-fail behavior, GDELT→GNews fallback. This adds significant context beyond annotations without contradicting them.

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

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

The description is dense but every sentence carries useful information—usage, output structure, fallbacks, limitations. It is somewhat long, but the complexity of the tool justifies the length; no filler.

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

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

Despite lacking an output schema, the description enumerates every return field (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and covers key constraints and edge cases (ticker vs CIK, name handling, patent API status). This makes the tool's behavior fully understandable.

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 concrete examples ("AAPL" or "0000320193"), explains zero-padding, and reiterates that names are unsupported. This goes beyond the schema's descriptions, clarifying the exact format and expectations.

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 produces a 'full cross-source profile of a US public company in ONE parallel call,' with concrete query examples. It distinguishes itself from siblings like compare_entities or deep_research by focusing on a single entity's holistic profile.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes that names are not supported and advises using resolve_entity first if only a name is available, providing clear when-to-use and alternative 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 destructiveHint=true and idempotentHint=true, so the description doesn't need to re-state destructive behavior. It adds a usage context about sensitive data, but this is more of a usage guideline than a behavioral disclosure. No additional behavioral traits like irreversibility side effects are described, matching the get_calls calibration where additions beyond annotations were minimal.

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: the first states the core functionality, the second covers usage and associated tools. Every clause earns its place, with no filler or redundancy.

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

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

Tool complexity is low (one required parameter, no output schema), and the description covers purpose, usage, and relationships with sibling tools. The annotations cover safety behavior, making the description sufficient for effective tool selection.

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

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

With 100% schema coverage and a clear parameter description ('Memory key to delete'), the schema already carries full meaning. The description adds only 'by key,' which reinforces but does not extend the parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb-resource pairing. It distinguishes itself from sibling tools like remember and recall by explicitly identifying deletion as the inverse operation.

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

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

Provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, giving clear alternatives and complementary 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 indicate read-only, idempotent, non-destructive. The description adds that it returns field names, descriptions, data types, which is useful output behavior. It doesn't contradict annotations and adds context beyond the safety profile.

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 tight sentences, no waste, front-loaded with action and resource.

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

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

Given the single parameter, safe operation, and presence of an output schema, the description covers the tool's purpose and output sufficiently. It could mention the returned format is a list but the schema covers that. Complete enough for a simple metadata lookup.

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

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

Only one parameter, property_id, is fully documented in the schema (100% coverage). The description reinforces that this is a GA4 property but doesn't add additional semantics or format constraints beyond 'numeric'.

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

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

The description uses a specific verb ('Discover') and identifies the resource ('available dimensions and metrics for a GA4 property'), and explicitly ties it to building accurate ga_run_report queries, distinguishing it from report execution tools.

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

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

It clearly states the context for use: before querying reports, to get accurate fields. It implies when to use (when needing valid dimensions/metrics) and points to ga_run_report as the downstream consumer. It doesn't explicitly mention alternatives or when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds the real-time nature and return focus, but no additional caveats or behaviors beyond annotations.

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

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

Two sentences, front-loaded with the core purpose, and includes a concrete example. 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?

With complete parameter schema, explicit annotations, and an output schema present, plus a simple tool scope, the description provides sufficient context for the agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so the parameter schema already documents all fields. The description adds a property ID example but no extra semantics 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 checks live user activity in a GA4 property and returns active user count and real-time engagement metrics. This specific verb+resource combination distinguishes it from siblings like ga_run_report (historical) and ga_get_metadata.

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 phrase 'right now' clearly signals real-time use, differentiating from historical reporting tools. However, it does not explicitly name alternatives or state when not to use, 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.

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint), and the description adds useful context about the accessibility scope ('properties you can access') and the specific return fields, going beyond the structured annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place by adding return-value details and a practical use case. No filler or redundancy.

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

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

With a simple list operation, full schema parameter coverage, an output schema present, and annotations indicating safety, the description is complete. It covers what the tool does, what it returns, and the typical use case without leaving significant gaps.

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

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

The input schema's descriptions cover 100% of parameters (page_size and page_token), so the description does not need to re-explain them. It adds no additional parameter-level detail, which aligns with the baseline for full 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 states 'List all GA4 properties you can access', identifying the exact resource and verb. It also specifies the returned data (property IDs, names, creation dates, account info) and distinguishes its purpose from sibling analytics tools by directing users to use it to find property IDs for ga_run_report.

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

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

The description explicitly tells when to use the tool ('Use to find the property ID for ga_run_report queries'), providing clear context. However, it does not mention when not to use it or name alternative tools, falling short of the highest bar for 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=false, so the safety profile is clear. The description adds useful behavioral context by stating that the result is 'aggregated data rows with dimension and metric values,' which clarifies the return shape 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 a single, front-loaded sentence that efficiently states the action, resource, key parameter categories, and return type. It includes useful examples without any filler or redundancy, making it highly concise and well-structured.

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

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

With 8 parameters, 4 required, nested objects, and 100% schema coverage, the schema carries most of the burden, and an output schema exists to define return values. The description provides sufficient high-level framing for a GA4 report tool, but slightly more explicit usage guidance would make it fully 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 schema descriptions cover all 8 parameters with examples and formats, so the baseline is 3. The prose description adds only general context about dimensions and metrics (e.g., 'city', 'pagePath', 'activeUsers', 'sessions') but does not meaningfully enhance the parameter-level details already present in the schema.

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

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

The description uses a specific verb 'Query' and clearly identifies the resource as GA4 analytics data with dimensions, metrics, and a date range, which returns aggregated rows. This content distinguishes it from sibling GA4 tools like ga_get_realtime and ga_get_metadata by emphasizing historical, report-style data retrieval.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it name exclusions. However, the mention of 'for a date range' implies it is for historical GA4 reporting rather than realtime or metadata queries, so the usage context is only weakly implied.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds process detail: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond the annotations by describing the fetch-and-extract workflow.

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: action + process + output format + use cases. Every sentence serves a purpose, and the main verb is front-loaded.

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

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

Despite no output schema, the description explains the output (single text blob, standard markdown) and provides use cases. Given the tool's simplicity (2 params) and strong annotations, the description is complete.

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

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

Schema covers both parameters fully (url and max_links with descriptions). The description does not add meaning beyond the schema, aside from implying any URL is valid. Given high schema coverage, score is baseline 3.

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

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

The description states a specific action ('Generate a production-ready llms.txt file for any URL') with a clear resource and process, and distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation. It includes the intended output format and use cases.

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

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

It provides clear context with 'Useful for' scenarios (getting a client's site indexed, drafting own project, auditing competitor), but does not explicitly name alternative tools or provide exclusions. Thus clear context but no explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description only needs to add non-obvious context. It does so by specifying that the tool returns only the caller's subscriptions and listing the exact fields returned. While pagination and rate limits are not mentioned, the annotation coverage plus return-field details are sufficient for this simple read-only tool.

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

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

Two sentences: the first states the action and return fields, the second gives usage guidance. No filler or redundancy, making it appropriately sized and front-loaded.

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

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

The tool is simple with a single optional parameter and no output schema. The description covers the return fields, caller scoping, and use cases, making it complete for an agent to decide whether to invoke and what to expect.

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

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

The sole parameter include_inactive is fully documented in the schema with a clear description and default value, so the description does not need to repeat it. Baseline 3 applies because schema coverage is 100% and the description adds no additional parameter meaning.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, params, etc.). It distinguishes the tool from siblings like subscribe and unsubscribe by focusing on the read-only listing operation.

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

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

The description explicitly advises using the tool to review current monitoring before adding subscriptions and to find an id to cancel, implicitly directing users to subscribe/unsubscribe as alternatives. This provides clear when-to-use context.

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

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

The description discloses behaviors beyond annotations: rate-limited to 5 per identifier per day, free and excluded from tool-call quota, daily team review, and roadmap impact. It also clarifies the scope boundary (only Pipeworx tools). No contradiction with annotations, and the description carries the transparency burden well since annotations provide little.

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

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

The description is longer than average but every sentence contributes unique value: purpose, usage cases, boundary conditions, rate limit, and roadmap impact. It is front-loaded with the primary action and avoids redundancy, though a slight trim could make it more concise without losing meaning.

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

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

For a feedback tool with no output schema and minimal annotations, this description is highly complete. It covers what to submit, when, exclusions (other MCP servers), message writing guidance, rate limits, and downstream effects. The user has all necessary information to use the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters (type, context, message), so the description adds little to parameter semantics. The only mild addition is the guidance to describe issues in terms of Pipeworx tools/packs, which reinforces but doesn't substantially expand on 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 tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb+resource with explicit categories (bug, feature/data_gap, praise) and distinguishes it from sibling tools by scoping feedback exclusively to Pipeworx-served tools, not other MCP servers.

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

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

Explicit when-to-use guidance is given ('Use when a tool returns wrong/stale data...'), along with when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'). It further provides practical tips like not pasting end-user prompts and describing issues in terms of Pipeworx tools/packs.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This informs the agent about freshness, data scope, and privacy implications, exceeding the annotation baseline.

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 (three sentences) and front-loaded with the core purpose. The numbered 'Useful for' list and clear separation of details (aggregation, PII, caching) make it well-structured. Every sentence contributes meaningful information without redundancy.

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

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

Despite lacking an output schema, the description sufficiently conveys what is returned ('top tools, top packs, and total call volume') and the data shape ('just (pack, tool, count)'). It also covers window behavior, caching, and privacy. For a simple one-parameter tool, this is complete and actionable 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?

The only parameter 'window' has 100% schema description coverage, so the baseline is 3. The schema already explains the enum values and trade-offs. The tool description merely mentions the window options without adding additional semantics beyond what's in the schema, so the score stays at the baseline.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It also differentiates from siblings by focusing on aggregate trending signals rather than individual queries or searches.

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 via the 'Useful for:' list (e.g., discovering hot data sources, confirming canonical tool choice, aligning with agent needs). It also gives guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly name alternative tools or include 'when not to use' 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses significant behavioral details: it 'walks child markets', 'drops will-person-X placeholder slugs', returns null signals on high placeholder fractions, and explains the fill check including 'realizable_edge_pp <= 0' meaning the edge is not in the book. It even instructs 'do not trade it'—rich, actionable 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?

The description is verbose but intentionally structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear front-loaded purpose. While longer than ideal, every section adds unique operational details that are necessary given the lack 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?

The description compensates for the missing output schema by outlining the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{...}'. It also covers safety rules (fill check, placeholders), making it complete for an agent to invoke correctly in all three 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?

Although schema coverage is 100%, the description adds substantial semantic depth to both parameters. For 'event', it provides example slugs and explains the per-event partition_check; for 'topic', it gives seed questions and describes cross-event scanning. This goes well beyond the schema's terse definitions.

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

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

The description opens with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes three modes (trending_scan, event, topic) with specific inputs, making the tool's purpose unambiguous and distinct from siblings.

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

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

Provides explicit when-to-use guidance for each call pattern: 'Call with NO args for a trending_scan... pass event for strongest... pass topic for themed cross-event scan.' It also recommends 'event' for specific markets and directs users to polymarket_fill_risk for custom sizing, clearly steering the agent to the right alternative.

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, but the description adds rich behavior: caching at KV level keyed on knobs, diagnostics explaining empty segments, edge_pp_net after slippage, 'rare-by-design' gates, and a 24h-move warning. This is far beyond annotation defaults.

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

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

Long and detailed, but front-loaded with the core purpose and structured with uppercase labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.). Every section adds value, though some model-specific thresholds (tennis 1.02, soccer 1.10) could arguably be moved to output schema or docs.

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, so description must explain return structure. It covers by_segment, fed_candidates/fed_note, _diagnostics, and the meaning of empty segments. Also covers knob effects, caching, and edge calculation - complete for a 9-parameter, complex scanning tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds important cross-parameter interactions: min_kelly never filters partition arbs because they always return kelly_fraction_half=0 at parent level, and min_partition_leg_kelly applies per-leg. It also groups knobs into 'TRADEABLE-EDGE' context.

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

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

Description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' - a specific verb+resource+scope. It clearly distinguishes this from arbitrage-focused siblings by emphasizing disagreement with Pipeworx data, not just market inefficiencies.

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 a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' But it doesn't explicitly contrast with alternatives like polymarket_arbitrage or edge_tracker, so exclusions are missing.

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

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

The description provides substantial behavioral context beyond the annotations: snapshot TTL limits, snapshots written only on cache-miss, meaning of data gaps, and decay computed from daily closes rather than intraday. These details are valuable for interpreting results and are not present in structured fields.

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

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

The description is long but well-structured with clear sections for core functionality, args, response, and limitations. Every sentence provides useful information; there is no fluff or redundancy.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, decay calculation). This is essential for the agent to correctly interpret results and is handled comprehensively.

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

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

The input schema already fully documents both parameters (100% coverage). The description repeats the defaults and window families but adds little new semantic meaning beyond the schema. The slight discrepancy between 'max 30' and 'clamp 2-30' is minor and does not add value.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes itself from sibling tools like polymarket_edges by focusing on edge history and decay rather than current edges.

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

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

The description gives clear context for when to use the tool: when evaluating whether an edge is fresh or aging ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies the alternative of looking at current edges via polymarket_edges, but does not explicitly name it. This is clear context without formal 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 destructive=false, and the description adds deeper behavioral detail: it 'walks the ladder,' returns a verdict (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk, and warns about partial basket fills converting arb into unhedged directional positions. This goes far beyond the annotations, explaining the tool's operational logic and failure modes.

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

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

Though long, the description is tightly structured with uppercase section labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and every sentence carries unique information. It front-loads the core purpose in the first clause and packs no filler.

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

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

With no output schema, the description compensates by enumerating all return fields per mode (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs[], etc.) and explains the risk context. It fully covers the tool's behavior, inputs, and the consequences of partial fills, making it complete for a complex analysis 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?

The schema already provides 100% parameter descriptions, but the tool description adds crucial semantics: the REQUIRES one of market/event constraint (absent from schema, where all are optional), the interpretation of size_usd as settlement notional in basket mode, and the default auto behavior for side. It also explains the clamping range and per-mode meanings, making the parameters unambiguous.

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

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

The description opens with a specific verb-resource pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and explicitly positions it relative to sibling tools (polymarket_arbitrage, polymarket_edges). This leaves no ambiguity about what the tool does.

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

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

The description explicitly instructs when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes and provides context about why it's necessary (theoretical overround on thin books is not capturable). There is clear guidance on prerequisites, though it does not enumerate when not to use it, which is acceptable given its role as a prerequisite check.

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?

Although annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description goes far beyond by disclosing behavioral nuances: it explains compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs. matched_pairs:0 with skipped_cross_type:0), temporal_alignment implications ('spreads are mathematically meaningless'), and counters like skipped_cross_type/subtype that reveal internal comparison logic. It even cautions that pre-mapped does not imply tradeability, which is rich, non-obvious 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 long (roughly 250 words) but highly structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a front-loaded purpose statement. Every sentence adds unique information—no filler. It is slightly verbose for a tool description, but the complexity of the tool and the absence of an output schema justify the length. A tightly edited version could earn a 5, but as written it is a strong 4.

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 provided, the description must carry the full burden of explaining return values. It does so effectively: it describes leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning scenarios, temporal alignment fields, and skipped_cross_type/subtype counters. It also provides concrete examples of topic shortcuts. Given the tool's complexity, the description covers all critical aspects needed for an agent to understand what the response contains and how to interpret it.

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

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

While the input schema already provides descriptions for all three parameters (100% coverage), the description adds significant semantic value. It explains that 'topic' auto-fetches matching events from each venue using pre-mapped shortcuts, and that 'kalshi_event_ticker' and 'polymarket_event_slug' act as overrides. This clarifies the interaction between parameters (e.g., override semantics) and the practical behavior of the 'topic' mode, which is beyond the schema's static descriptions.

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

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

The description opens with a specific, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's function, the two venues involved, and the concept of a spread. It also distinguishes itself from sibling tools like 'polymarket_arbitrage' by emphasizing the cross-venue comparison and the conditions under which the spread is meaningful, making the purpose precise and differentiated.

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 defines two usage modes (topic vs. explicit kalshi_event_ticker + polymarket_event_slug) and explains when each is appropriate. It also provides strong when-not guidance, notably: 'when they aren't the tool says so' and 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it does not name alternative sibling tools or explicitly state 'use this instead of X,' which prevents a perfect 5.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key argument lists all saved keys. 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 three concise sentences, each earning its place: the first states the core action, the second gives concrete use cases, and the third explains scoping and companion tools. There is no redundant wording or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It clarifies what is returned (a value or list of keys), when to use it, and how it relates to remember/forget. The annotations handle safety, and the schema handles parameter structure, leaving no critical gaps.

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

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

The schema fully documents the optional key parameter, including the 'omit to list all keys' behavior. The description adds the insight that keys are 'previously saved via remember,' which clarifies the provenance of valid keys and reinforces the parameter's semantics beyond the schema text.

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

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

The description uses a specific verb-resource pairing: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by naming remember and forget as companion operations, and the resource is unambiguous (a saved memory key).

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

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

The description gives explicit use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also references companions (remember to save, forget to delete), but it does not explicitly state when not to use this tool or list alternative tools for similar purposes.

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 annotation readOnlyHint=true conflicts with the description's statement that setting mark_read:true will 'flag returned events read', which is a state mutation. The description discloses this side effect, but the annotation contradicts it, triggering the annotation contradiction rule. This is a serious inconsistency that could mislead an agent about the tool's side effects.

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

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

The description is well-structured, front-loaded with the primary purpose, and every sentence provides useful information—return fields, filters, read-state behavior, and alternative access. No fluff or redundancy.

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

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

It explains return payload contents (source, citation_uri, raw payload) despite no output schema, and mentions polling suitability and an HTTP alternative. It does not explicitly mention the 'unread_only' parameter, but the schema covers it, so this is a minor gap. Overall, it is quite complete for a read-focused tool.

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

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

Although schema coverage is 100%, the description adds value by giving a concrete example for type ('sec_8k'), reinforcing the ISO format for since, and explaining the behavioral effect of mark_read (only newer events on next call). This goes beyond the basic schema descriptions.

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

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

The description opens with a specific action ('Pull fired events from your subscription feed') and clearly identifies the resource (persisted alert feed). It distinguishes this from sibling tools like recent_changes or list_subscriptions by focusing on fired alerts with filtering and read-state management.

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

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

It provides clear context for usage: you can filter by type/since, set mark_read, and poll the same feed via an HTTP endpoint for scripts. However, it does not explicitly state when to use this over sibling tools like recent_changes or when not to use it, so it falls short of a perfect 5.

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

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

The description goes beyond the readOnly/idempotent/destructive annotations by revealing the fallback chain (GDELT preferred, GNews when rate-limited or 5xx), the USPTO soft-fail due to PatentsView sunset, and the return format (changes[] grouped by source + total_changes + citation URIs). No contradictions with annotations.

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

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

The description is long but dense and well-organized. It front-loads common query phrasings, then delivers source behavior, fallbacks, date formats, and return shape without redundancy. Every clause adds operational 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 there is no output schema, the description adequately explains the return structure (changes[], total_changes, pipeworx:// citation URIs) and source-specific failure modes. It also names the alternative tool for different user needs, making the context complete for a complex multi-source 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?

The input schema already covers all 3 parameters with 100% coverage, providing a strong baseline of 3. The description adds practical semantics with relative shorthand examples for 'since' ('7d', '30d', '3m', '1y'), example values for ticker/CIK, and typical usage guidance ('Use 30d or 1m for typical monitoring'), bringing it to a 4.

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

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

The description clearly states that the tool returns a change feed for a company over a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. This is a specific verb+resource with clear scope, and it distinguishes recent_changes from sibling tools like entity_profile or compare_entities.

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

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

Provides explicit when-to-use guidance with natural-language triggers like 'What's new with X' and calls out an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This clearly delineates use cases.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds scoping ('scoped by your identifier'), persistence details (authenticated users persistent, anonymous 24 hours), and the ability to pair with recall/forget. 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 sentences, front-loaded with the core action, then usage context, then storage semantics and sibling pairing. No filler; each sentence contributes essential 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 two-parameter tool with no output schema, the description covers purpose, usage, persistence, and retrieval/deletion pairing. It is sufficiently complete for an agent to select and invoke correctly.

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

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

The input schema already provides 100% coverage with examples for key and value. The description adds minimal extra meaning by mentioning key-value pair scoping, but it doesn't go beyond baseline 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later', clearly indicating a memory-write operation. It distinctly differentiates from siblings like recall and forget by stating it stores data and pairs with recall/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?

It explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives directly by saying 'Pair with recall to retrieve later, forget to delete', giving clear usage boundaries.

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

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

Beyond the readOnly and idempotent annotations, the description reveals internal cascading lookups, auto-disambiguation, and citation URI returns. This adds useful behavioral context without contradicting annotations.

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

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

The description is lengthier than typical but well-organized, starting with example queries and then detailing supported types. Every sentence contributes value, though a bit dense.

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 compensates by specifying exact return fields and citation URIs for each type. It also mentions the cascading lookup complexity, making the tool's behavior understandable.

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 descriptions are minimal, but the tool description enriches both parameters with accepted input formats (ticker, CIK, name for company; brand/generic for drug) and notes auto-disambiguation, going well beyond 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 states the tool's function: resolving user-spoken names to canonical identifiers (ticker, CIK, RxCUI). It provides concrete examples and distinguishes itself from siblings by focusing on ID lookup.

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 FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not mention when not to use it or name alternative tools, which prevents a 5.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds process details (probes each entity, ranks by score, surfaces most/least recognized) and return fields, providing useful behavioral context without conflicting 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 concise sentences plus a quoted example. Front-loaded with the main verb and resource. Every word earns its place; no fluff.

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

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

The description covers what the tool does, the use case, the process, and the return format. With full schema coverage and strong annotations, no critical information is missing.

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

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

Schema coverage is 100%, so the schema already explains all parameters. The description adds narrative context around 'entities' (your brand + competitors) but does not add new parameter-level details beyond what the schema provides. 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 compares AI visibility across multiple entities side-by-side, explicitly naming the underlying probe (ai_visibility_check) and the output (ranked list with score, confidence, signal density). This distinguishes it from single-entity tools and generic comparators like compare_entities.

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

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

The description gives a clear use case (competitive AI-marketing audits) and an illustrative example. It implies when to use this tool instead of ai_visibility_check (multi-entity comparison), but does not explicitly mention alternatives or exclusions, so a small deduction.

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

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

Beyond annotations, the description discloses composite fan-out behavior, partial failure degradation, a 5-30s first-measurement latency, and the sources_failed field. It also enumerates the output structure. This significantly exceeds annotation coverage and aids the agent in anticipating side effects and delays.

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

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

The description is dense but well-structured: purpose, usage, outputs, ecosystem limitation, and failure behavior. Each sentence earns its place, and the most decision-relevant information is front-loaded.

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

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

Given the tool's moderate-to-high complexity (composite sources, multiple output fields) and no output schema, the description fully covers return values, failure modes, and limitations. It leaves minimal ambiguity for an agent invoking this tool.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema for package and version. It reinforces that version defaults to latest but does not introduce new constraints or semantic depth, so the baseline of 3 is appropriate.

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

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

The description opens with a specific composite purpose ('should I add this npm package to my project' check) and details the fan-out across deps.dev and bundlephobia, clearly distinguishing it from any sibling tool. It names the exact data sources and categories, making the tool's function 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?

Explicitly states when to use ('whenever an agent asks is X safe / popular / small') and provides exclusions ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is textbook guidance for 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses valuable behavioral details: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, returns character offsets for verification, has a 200K char cap with truncation flagging. This adds significant context about how results are computed and limited, which the annotations do not 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 four sentences, tightly structured: purpose first, then when-to-use, then pairing information, then technical mechanics. Every sentence carries information, with no redundancy or filler. The use of capitalization for 'INSIDE' highlights the core scope.

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 moderate complexity, the description covers inputs, outputs (top-N passages with offsets and similarity scores), usage context, and a key limitation (truncation). With full schema coverage and no output schema, the description is complete enough 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?

Schema coverage is 100%, so the baseline is 3. The description adds contextual examples for the query parameter and clarifies that 'text' is previously fetched content, but these do not materially exceed the schema descriptions. No additional parameter semantics are provided 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 clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the action (semantic search), the resource (a fetched record), and the inputs (text and natural-language query), which distinguishes it from sibling tools like ask_pipeworx_grounded that operate at a different stage.

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 when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names a complementary alternative (ask_pipeworx_grounded) and describes how they pair, making the decision boundary 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?

Beyond the annotations (readOnly=false, idempotentHint=true, etc.), the description adds critical behavioral context: OAuth account requirement, anonymous/BYO limitation, always-on feed via recent_alerts or a public endpoint, optional email/SMS channels, phone verification requirement, SMS daily cap, and webhook auto-disable after 10 consecutive failures. This provides substantial safety and operational 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?

The description is long and dense but well-structured: it opens with the core purpose, then covers supported types, delivery channels, and constraints. It repeats some schema details, but the additional examples and caveats make each section earn its place. Slightly more trimming could improve it, but it remains readable and scannable.

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

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

For a tool with rich schema annotations and no output schema, the description is highly complete: it states what is created, the return value (subscription id), required account type, all supported event types with parameter examples, delivery options, and notable limits. It fully equips an agent to decide whether and how to call subscribe.

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 contains detailed parameter descriptions. The description adds extra semantic enrichment—e.g., 'items:["5.02"] = officer change', 'Polymarket↔Kalshi cross-venue mispricings', and concrete examples for each subscription type—which helps the agent construct valid params beyond raw schema definitions.

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

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

The first sentence specifies a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It further enumerates supported subscription types and the return value (subscription id), making its purpose unambiguous. It also distinguishes itself from sibling tools like list_subscriptions and recent_alerts by describing the persistent feed.

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 concrete guidance on when to use the tool: to persist a proactive monitoring subscription to live event streams, with explicit type-specific parameter examples. It also notes when not to use it—anonymous and BYO accounts cannot persist subscriptions—and mentions prerequisites like verified phone for SMS. It could more explicitly contrast with alternative tools, but the context is strong.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context beyond that: it returns category-bucketed example questions drawn from the live catalog, and explains the effect of passing or omitting the topic parameter. It does not contradict 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?

Though longer than a one-liner, every sentence earns its place: triggering example questions, output structure, live-catalog source, topic behavior, and explicit usage-first guidance. It is front-loaded with the key purpose and remains information-dense without waste.

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 simple shape (zero required parameters, no output schema) and rich annotations, the description fully covers what the tool does, what it returns, how to vary results, and when to use it. No meaningful behavioral or usage gaps remain.

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

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

Schema coverage is 100% for the single optional topic parameter, so the schema already documents meaning and the omit-for-full-spread behavior. The description adds examples like 'finance', 'pharma', 'betting', but these are illustrative rather than genuinely new semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: it returns category-bucketed example questions with the exact tool and argument shape, and clearly identifies itself as the onboarding entry point. This distinguishes it from sibling tools like ask_pipeworx or discover_tools by framing it as the meta-level guide for what can be asked.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This is a clear directive for when to use it and positions it against related tools by naming the meta-tools to learn about.

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 key behavioral details beyond annotations: soft-delete (deactivated, not deleted), ownership enforcement, and impact on recent_alerts. It is consistent with the idempotentHint and destructiveHint annotations.

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

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

The description is concise, front-loaded with the main purpose, and 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?

For a single-parameter tool with no output schema, the description covers the purpose, constraints, and aftermath (deactivation with retained history) sufficiently; nothing critical is missing.

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

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

The schema already fully describes the `id` parameter as a subscription id returned by subscribe. The description only restates it briefly without adding new semantic value, so it meets the baseline for full 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 states the action (cancel) and resource (subscription by id), and clarifies it's a deactivation, effectively distinguishing it from 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?

Provides ownership constraint and notes historical access via recent_alerts, but does not explicitly mention alternatives or when-not-to-use. The purpose is clear enough that this is the tool for canceling subscriptions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description details the SEC EDGAR + XBRL fast path with exact percent-delta math, the grounded pipeline fallback, the list of possible verdicts, pipeworx:// citations, and tolerance behavior. This is substantial additional context beyond annotations, with no contradictions.

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

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

The description is dense but every sentence earns its place: trigger phrases, use case, routing, output summary, and an efficiency note. It is front-loaded with the purpose, making it efficient despite the detail needed for a complex verification 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?

Even without an output schema, the description fully explains the returned verdict types, grounded or structured actual value with citation, and reasoning. It covers both processing pathways and explicitly states what the tool replaces, making it standalone for an agent to select and use correctly.

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

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

Schema coverage is 100%, but the description adds crucial semantics: tolerance_pct override behavior, default cap of 5, and a recommended 1–2 range for hallucination detection. It also provides clear natural-language claim examples that enrich the schema's plain parameter definitions.

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

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

The description uses a specific verb+resource: 'natural-language claim verification against authoritative sources.' It lists trigger phrases and clearly distinguishes itself from sibling research tools by focusing on verifying a user's fact claim, with a structured fast path for company-financial claims and a grounded pipeline for everything else.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates routing behavior based on claim type and notes that the tool replaces 4–6 sequential calls, providing clear context on when to invoke it.

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