tle

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

Annotations already declare readOnly, idempotent, non-destructive, so the description's added value lies in return format and cost behavior. It reveals that the default model is free, that passing _apiKey incurs direct Anthropic costs, and that the response contains per-model score, confidence, signals, raw_response plus a combined view. This is meaningful behavioral context. No contradiction.

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

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

Three sentences, front-loaded with the core purpose, followed by model/cost details and use cases. Every sentence contributes unique information with no redundancy, earning a 5.

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

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

The description covers the return shape, model options, cost implications, and typical use cases. Since there is no output schema, providing the response structure is important and done well. It is complete for a moderate-complexity tool with full schema coverage.

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

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

The schema has full descriptions for all 4 parameters (100% coverage), so the baseline is 3. The description adds extra nuance by specifying the default model ('Workers AI Llama-3.3-70b'), clarifying that _apiKey is only needed for Anthropic and that the key is passed directly through. This enhancement justifies a 4.

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

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

The description opens with a specific verb 'Probe' and identifies the resource 'one or more LLMs' and the goal 'score visibility (0-100) per model.' It clearly distinguishes itself from sibling tools by focusing on AI visibility scoring rather than direct Q&A or research. The output format and use cases further clarify its unique role.

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 states concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to add Anthropic via _apiKey. However, it does not explicitly name sibling alternatives or provide when-not-to-use guidance, so it earns a 4 rather than 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 indicate read-only/open-world/idempotent behavior. The description adds useful context about routing and stable citation URIs, but doesn't detail rate limits or error behavior. It does not contradict annotations.

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

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

Despite being long, the description is front-loaded with a directive ('PREFER OVER WEB SEARCH') and every sentence adds value: use cases, examples, alternatives, and context. 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?

For a router tool with no output schema, the description thoroughly covers the output format (structured answer with citations), use coverage, alternatives, and specific examples. It's complete enough 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 schema already documents the 'question' parameter and its aliases with 100% coverage. The description provides example queries, but adds little beyond the schema's own explanation, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: routes questions to 5,529 tools across 1,455 sources, fills arguments, and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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 instructs to prefer this tool over web search for factual queries, provides example queries, and explains when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (broad multi-part questions).

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, idempotent, and non-destructive behavior. The description adds valuable context about the beta nature, including the current state (no active candidate) and that behavior matches ask_pipeworx exactly right now, plus the experimental edge. This goes 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 concise and front-loaded with the key concept (beta version), but contains slight redundancy (repeats identical nature and current match to ask_pipeworx). Still, every sentence contributes to understanding the tool's purpose and usage.

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

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

For a router tool with strong annotations and a self-describing schema, the description sufficiently covers the beta state, comparison to the stable version, and usage intent. The lack of an output schema is mitigated by the statement that the response shape is identical to ask_pipeworx, and no further return-value details are needed.

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 fully described in the schema, including aliases for 'question'. The description adds no additional parameter meaning beyond 'same arguments' as ask_pipeworx, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with identical scope and behavior. It explicitly mentions the same 5,529 tools, arguments, and response shape, distinguishing it from the stable ask_pipeworx and other 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 provides explicit usage guidance: use it like ask_pipeworx when you want the newest routing with experimental improvements, and notes results are compared against the stable router. It also clarifies that it is a full working router, not a fallback, implicitly steering users to ask_pipeworx for stable results.

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

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

Annotations already indicate readOnly/openWorld/idempotent/non-destructive, but the description goes beyond by disclosing the extra LLM call cost, the exact refusal reasons (not_in_source, no_tool_match, etc.), and that it only uses tool result content. It also states the return shape on success and failure, adding significant behavioral context 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 longer than average but front-loaded with the core purpose, then systematically explains mechanism, output format, use cases, and cost tradeoff. Every sentence contributes value, though it could be tightened slightly without loss of information.

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

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

There is no output schema, so the description compensates by fully specifying the success return object and each refusal reason enum. It also explains the routing across 5,529 tools/1455 sources, the cost difference, and when to prefer the sibling tool—making the description comprehensive for a complex tool.

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

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

Schema description coverage is 100% with detailed descriptions of the question parameter and its aliases. The description adds no new parameter meaning but the schema already fully clarifies; a baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' for high-stakes reads, and explicitly differentiates from sibling ask_pipeworx by describing its extraction-from-results approach and refusal behavior. This gives a specific verb+resource+scope and distinguishes it from alternatives.

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

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

It provides explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), and contrasts with the alternative ('prefer ask_pipeworx for casual lookups'). This is clear usage direction with 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 mark read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral detail beyond annotations: resolver confidence levels, low-confidence short-circuit behavior, closed-market status codes, wide-spread illiquidity flags, news fallback mechanics, and resolution-rule risk (e.g., flat-50¢ void refunds). This is rich, actionable context for invoking the tool safely.

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 tightly organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence carries domain-specific value. It's not concise in word count, but for a complex tool with many behavioral nuances, the structure makes it navigable and information-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?

No output schema exists, so the description must fully explain return values—and it does. It covers result.market fields, result.analysis edge metrics, evidence keying, resolver contract with confidence levels and alternatives, parent_event extractor for partitioned events, news fallback fields, safety statuses for low-confidence and closed markets, and cancellation-rule risk. Nothing critical is missing.

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

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

Schema covers 100% of parameters with descriptions. The description adds semantic depth for the 'market' parameter (accepted formats and resolver behavior) and explains include_raw's trade-off between summarized evidence and full payloads. It clarifies the fan-out logic but doesn't add much beyond the schema for 'depth'.

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

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

The description states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the input (slug, URL, or question text) and output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like arbitrage or edge tracking.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides concrete fan-out examples for different bet types. It doesn't explicitly state when NOT to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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 (readOnly, non-destructive). The description adds valuable behavioral context: pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. This goes beyond 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 dense but every sentence contributes. It front-loads with trigger phrases, then explains data sources, edge cases, and output. Slightly long but efficient for the complexity.

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

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

For a comparison tool with no output schema, it adequately covers data sources, sorting behavior, output citations, and use cases. It even mentions the 2–5 entity limit and handles fiscal year nuances. Complete enough 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what data is pulled for each type (revenue/net income for companies, FAERS/trial counts for drugs) and gives concrete examples for the values array. This compensates for minimal schema descriptions.

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

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

The description clearly states the tool compares 2–5 companies or drugs side-by-side, with specific verb 'compare' and resource types. It includes trigger phrases and explicitly contrasts with sequential lookups, distinguishing it from sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains when to use company vs drug types. This gives clear guidance on when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial context beyond these: latency expectations, never-invented gapped findings, fetchable citations, semantic excerpting, contradictions scan, and depth-specific hop behaviors. 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 and dense, but every sentence contributes distinct value: account requirements, alternative tool, data source scope, output format, depth semantics, citation guarantees, and performance. It is front-loaded with critical account and usage-context information, though slightly verbose for a tool description.

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

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

With no output schema, the description thoroughly explains the return findings packet including verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field, and citation_uri. It also covers latency, paid tiers, and semantic excerpting, making the tool's behavior fully predictable for an agent to select and invoke.

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

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

Input schema covers both parameters with 100% description coverage, so baseline is 3. The description adds value by explaining depth-level consequences (gap recovery for standard, lead chasing and paid requirement for thorough), latency implications, and providing examples of well-formed questions, going beyond the schema's own descriptions.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's 1455 structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly contrasts with open-web search and distinguishes from ask_pipeworx, making the purpose unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part questions over structured data, while ask_pipeworx is recommended for single lookups and breaking/current news. Also covers account prerequisites and free/paid tier limitations, ensuring the agent can decide 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 already cover readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: returns top-N relevant tools with names, descriptions, and full input schemas, ready to call directly with no second lookup. This clarifies the output and interaction model 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 three sentences, each earning its place: purpose, usage context, and return format. The domain list is long but useful for scoping. No redundant or vague language; structure front-loads the core purpose.

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

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

As a discovery tool without an output schema, the description adequately explains the return value (top-N relevant tools, schemas included), the intended first-call usage, and the scope. It gives enough information for an agent to invoke it correctly and know what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that query is a natural language description but does not add new parameter meaning beyond the schema's own thorough descriptions (including aliases). No additional semantics are provided, so the score stays at 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 purpose: 'Find tools by describing the data or task.' It specifies a distinct verb (find/discover) and resource (tools), and differentiates itself from siblings by positioning itself as a first-stop discovery tool, not a specific data lookup. The list of domains further clarifies scope.

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 when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and advises calling it FIRST when many tools are available. It implies alternatives (the specific tools), but doesn't explicitly state when not to use it, 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 declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context: fans out across multiple sources, returns specific fields (CIK, filings, fundamentals, patents, news, LEI), notes the USPTO patents API sunset with soft-fail, and describes the GDELT→GNews fallback. This goes well beyond structured annotations.

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

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

The description is dense but front-loaded with examples and the core purpose. It contains some redundancy with the schema (repeating name limitations), but every clause adds useful behavioral or contextual information. Slightly long but well-structured with lists and clear sections.

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?

This is a complex tool with no output schema, yet the description covers inputs, return fields, sources, fallbacks, soft-fail behavior, and usage preferences. It even details the content of returned structures (e.g., up to 5 filings with URIs). This is remarkably 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 input schema provides 100% coverage with clear descriptions for both parameters. The description repeats these meanings (e.g., ticker or zero-padded CIK, names not supported) but does not add new semantics beyond what the schema already specifies. Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'full cross-source profile of a US public company in ONE parallel call' with multiple concrete example queries. It differentiates itself from sibling tools by explicitly noting it should be preferred over chaining single-pack lookups and that resolve_entity is needed for name-only input.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and clearly states an exclusion (names not supported, use resolve_entity first). This directly tells the agent when to use this tool versus alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to re-state safety. It adds context about clearing sensitive data and when deletion is appropriate. No contradiction, but doesn't describe behavior on non-existent keys, though idempotent hint covers that implicitly.

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, action first, usage guidance second. No redundant wording. Perfectly sized.

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?

Simple 1-param tool with strong annotations (destructive, idempotent) and schema. Description covers purpose and usage. Could mention return value or irreversible nature, but annotations already convey the destructive aspect. Adequate.

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

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

Schema has 100% coverage with a clear description of 'key' as 'Memory key to delete'. The description's phrase 'by key' adds no additional semantic detail. Baseline 3 applies.

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

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

Description uses specific verb 'Delete' with resource 'previously stored memory' and identifies key as the identifier. Clearly distinguishes from sibling tools 'remember' and 'recall' by contrasting its function.

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 use conditions: stale context, task completion, clearing sensitive data. Mentions pairing with remember and recall, implying alternatives. Lacks explicit exclusion conditions, so not a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds behavioral context by explaining that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', and that output is a 'single text blob ready to drop at site-root/llms.txt'. This goes beyond the annotations by detailing the operation and output format, though it does not cover edge cases like error handling.

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

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

The description is three sentences, front-loads the main purpose, and includes a useful 'Useful for' section without redundancy. Every sentence contributes meaning: the action, the output format, and the use cases. It is 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?

The tool has only 2 parameters, no output schema, and simple behavior. The description fully covers the operation, the output format, and the intended use cases. It explains the return value ('single text blob') and the processing steps, making it 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?

Schema description coverage is 100%, so both parameters (url and max_links) are fully documented in the schema. The tool description does not add any additional parameter semantics. According to the rubric, the baseline is 3 when the schema fully covers parameters, and there is no extra value added here.

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 with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also describes the process (fetches, extracts, emits) and the output format, making it distinct from sibling tools like scan_competitor_ai_presence which focus on analysis rather than generation.

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

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

The 'Useful for' section explicitly lists three scenarios: client indexing, own project drafting, and competitor auditing. This provides clear context for when to use the tool, though it does not mention alternatives or exclusion criteria. Therefore it falls short of a 5 but is more than a vague implication.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail about the response structure (satellite name, epoch, TLE lines) beyond those annotations. No contradictions found.

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 action verb and resource, and contains no redundant information. Every sentence adds value.

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

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

The tool is simple with one parameter, an output schema exists, and annotations cover safety. The description fully explains the purpose and what is returned, with no significant gaps for the agent to proceed.

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

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

Schema coverage is 100% with a detailed description and examples for norad_id. The tool description does not add any parameter 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 uses the specific verb 'Fetch' with the resource 'Two-Line Element (TLE) set', clearly scoping by NORAD catalog ID. It also lists the return fields (satellite name, epoch date, TLE lines), which further distinguishes it from sibling search_satellites.

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

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

The description implies usage when a NORAD ID is known, but it does not explicitly state alternatives or when not to use this tool (e.g., use search_satellites when the ID is unknown). No explicit prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by disclosing the non-obvious ordering caveat (catalog-based, not epoch-based) and its approximation quality. It doesn't discuss pagination, rate limits, or result format beyond what the output schema would 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?

Two well-crafted sentences with zero waste. The first establishes purpose and sorting logic, the second delivers a critical caveat. Every phrase earns its place and the most important 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?

The tool has only one simple parameter with a default, complete annotations, and an output schema. The description covers the tool's purpose, sorting semantics, and caveats thoroughly. Given this simple complexity profile, the description is essentially complete for agent invocation.

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

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

Schema description coverage is 100% — the single 'limit' parameter is fully documented in the input schema with its default value of 10. The description adds no semantic detail beyond the schema, so baseline 3 is appropriate per the rubric.

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

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

Description clearly states it lists newest satellites in NORAD catalog by highest catalog number, which serves as a proxy for most-recently-launched. It uses a specific verb+resource combo (list satellites) with a clear sorting rationale. This distinguishes it from siblings like search_satellites and get_tle by emphasizing the catalog-order listing semantics.

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

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

The description implicitly communicates when to use this tool: when you want recent satellites via catalog number. The explicit note that it orders by catalog entry rather than TLE epoch and that upstream offers no epoch-date sort provides valuable context that prevents misuse, though it does not name specific alternative tools explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by scoping to the caller's subscriptions, outlining the returned fields, and clarifying the default behavior of listing active subscriptions only. This goes beyond the annotation-provided 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?

The description is two sentences with no fluff: it leads with the action and object, lists return fields, and then gives targeted usage context. Every sentence contributes useful information.

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

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

For a simple read-only list tool with one well-documented optional parameter and no output schema, the description fully covers purpose, scope, return format, and practical use. The include_inactive parameter is already explained in the schema, so no further detail is needed 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% and the sole parameter include_inactive has a full description in the schema. The tool description does not discuss this parameter, but it reinforces the default 'active' scope. Since the schema already documents the parameter, a baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource ('List the caller's active subscriptions') and specifies the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This clearly distinguishes it from sibling tools like subscribe and unsubscribe while providing concrete scope.

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 states explicit use cases: review monitoring before adding more subscriptions, and find an id to cancel. It doesn't name alternative tools like subscribe/unsubscribe directly, but the context clearly implies these actions, giving practical guidance without 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 annotations (which indicate this is not read-only, not idempotent, etc.), the description discloses several crucial behaviors: the claim_token flow for anonymous submission and later status checks, a rate limit of 5 per identifier per day, and that it is free with no quota consumption. It also notes the team reads digests daily, setting expectations on response.

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 adds operational or scoping information. It is front-loaded with the core purpose, then systematically covers exclusions, token handling, rate limits, and cost. No wasted words, though it could be tightened slightly by merging some clauses.

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

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

Despite having no output schema, the description complete enough for the tool: it explains what qualifies as feedback, how to scope it, what happens when unauthenticated, how to retrieve resolution status, and the daily limit. The sibling tools are clearly excluded by the explicit boundary of 'ONLY for tools served by this Pipeworx connection.'

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 has 100% description coverage, so the baseline is 3. The description adds value by giving a concrete example of using claim_token (pipeworx_feedback({claim_token:"pwfb_…"})) and explaining how the context object maps to tool/pack/vertical, which complements rather than repeats 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings (e.g., ask_pipeworx) by restricting feedback to Pipeworx-served tools and naming the four feedback types (bug, feature, data_gap, praise).

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 by enumerating scenarios (bug, feature/data_gap, praise) and when-not-to-use by stating that tools from other MCP servers should be reported to that server, not here. It also instructs users to describe issues in terms of Pipeworx tools/packs and avoid pasting end-user prompts.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy traits, and caching behavior, which enriches the agent's understanding of what to expect.

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 somewhat longer than minimal but well structured: a lead sentence, a return-value sentence, a numbered use-case list, and a final technical note. Every sentence contributes meaning without redundancy. It is not as terse as the 5 exemplar, but it earns its length with substantive content.

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

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

With no output schema, the description still conveys the core return content ('top tools, top packs, and total call volume') and important behavioral details (no PII, derivation from analytics, cache times). For a simple one-parameter tool with robust annotations, this is largely complete. It might have elaborated on exact response format, but that is not critical for selection and invocation.

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

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

Schema coverage is 100% for the single optional window parameter, with a clear enum and description in the schema itself. The description mentions the same window values ('24h, 7d, or 30d') but adds no additional semantic detail beyond the schema. Baseline 3 is appropriate since the schema carries the 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This identifies the verb (returns) and resource (trending Pipeworx usage). It clearly distinguishes this from siblings like discover_tools or list_recent by focusing on aggregate agent call trends.

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: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' However, it does not mention when not to use this tool or name specific alternatives (e.g., discover_tools), so it lacks the explicit exclusion that would warrant 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses rich behavioral details: the Jaccard similarity threshold for semantic pairing, placeholder filtering rules, fill-check logic with realizable_edge_pp, and the explicit warning 'do not trade it' when the edge is only at last-trade. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK). It front-loads the core purpose and then provides necessary operational details. Some sentences are dense and could be tightened, but the structure earns the length and avoids redundancy.

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

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

This is a complex tool with three modes, multiple filters, and a fill-check subprocess. The description covers inputs, outputs (including response shape with opportunities[] and partition_check object), edge cases (e.g., null arb signal, low similarity, thin legs), and cross-references to a sibling tool for custom sizing. Since there is no output schema, the description appropriately explains return values in full.

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 has 100% description coverage for event and topic, but the description adds substantial semantics: it explains that no args triggers trending_scan, gives concrete examples for both parameters, and clarifies which parameter is recommended in different scenarios. The description also surfaces the distinction between event-mode and topic-mode internal workings, going far beyond the schema's basic field 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by detailing three distinct modes (trending_scan, event, topic) with concrete examples like event slugs and seed questions. The purpose is unambiguous and differentiates from similar tools.

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

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

The description explicitly tells when to call with NO args for trending_scan, when to use 'event' for a specific market, and when to use 'topic' for cross-event scanning. It even states that cross-event mode catches patterns single-event misses and directs users to polymarket_fill_risk for custom sizing. This is excellent when/when-not guidance.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses substantial behavioral detail: 1h KV caching, the 'Market moved X.Xpp in 24h' warning, diagnostics showing 'why a segment is empty,' and a reliability caveat on the Fed signal ('unreliable at meeting-month horizons without paid OIS/SOFR-futures data'). No contradiction with the annotations is present.

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

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

The description is front-loaded with a clear one-sentence purpose, but it is extremely long and dense, mixing model-family details, thresholds, response fields, and caching behavior into a single block. While almost every sentence contributes unique information, the length and heavy use of ALL-CAPS segment names reduce scannability; a more trimmed version would be better suited for a tool description.

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

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

No output schema exists, so the description compensates by specifying response structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the 24h-move warning. Given the tool's complexity and zero required parameters, the description is complete enough for an agent to invoke the tool and interpret its results correctly.

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

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

Schema coverage is 100% and every parameter already has a descriptive schema entry, so the baseline is 3. The description adds decision-oriented meaning beyond the schema: min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable,' and min_partition_leg_kelly explains that parent-level kelly is 0 by design and the knob applies instead to per-leg Kelly inside top_legs—valuable extra 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?

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' a specific verb+resource+scope that clearly states the core function. It also frames the use case ('what should I bet on today') and differentiates itself from generic market listing by emphasizing Pipeworx disagreement and opportunity discovery without paging.

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 the intended use case ('Built for "what should I bet on today"') and gives operational context such as 'discover opportunities without paging hundreds of markets.' It does not explicitly name alternative sibling tools or exclusion conditions, but the 'Fed bets surface here, excluded from ranking' note and 'rare-by-design' caveats provide clear context for when certain opportunities will appear.

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 substantial behavioral details beyond the readOnly/idempotent annotations: 60-day snapshot TTL, decay computed from daily closes (not intraday), snapshots written on cache-miss with gaps meaning no scan, and response semantics. This provides deep context that annotations alone do not 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 well-structured, covering purpose, arguments, response format, and limits in a compact, organized manner. Every sentence provides useful information, with no wasted words.

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

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

For a tool with no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), parameter semantics, and limitations. It gives the agent everything needed to understand the tool's behavior and expected output.

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

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

The input schema already provides complete descriptions for both parameters, including defaults and clamps (100% coverage). The description repeats the parameter names and defaults but adds little new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers the question 'how long has this edge existed and is it shrinking?'. It differentiates from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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

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

The description implies when to use the tool by stating that a fresh wide edge and a 3-week-old wide edge are different trades, suggesting it is for evaluating edge age and trend. However, it does not explicitly name alternative tools or provide exclusion criteria, though the sibling list makes the distinction 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 readOnly, openWorld, idempotent, and non-destructive. The description goes beyond by disclosing internal behavior such as 'walks the ladder', the verdict categories (clean|degraded|cannot_fill), and the risk of 'forced_directional_risk' from partial basket fills. This contextualizes the safety hints and adds meaningful operational 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 long and dense, but every sentence adds critical operational context. It front-loads the core purpose, then details modes and parameters, and ends with explicit usage triggers. Minor loss for being a single wall of text, but no wasted words.

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

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

Without an output schema, the description must explain return values, and it does: it enumerates the full set of output fields for both single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket modes (theoretical_sum, realizable_sum, capture_ratio, thin_legs[], etc.). It also covers edge cases like 'cannot_fill' and 'forced_directional_risk', making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description substantially enriches each parameter. For example, size_usd is defined differently for single-market ('max spend on buys, target proceeds on sells') vs basket ('settlement notional S — shares per leg; each share pays $1'), and side default logic is explained. This adds value beyond the schema.

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

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

The description opens with a specific, technical purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from siblings by naming polymarket_arbitrage and polymarket_edges and by defining two distinct modes (single-market and basket).

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing partial fills converting arbitrage into unhedged directional positions, making it clear when alternatives are inappropriate.

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=True, idempotent=True, openWorld=True, and non-destructive. The description adds rich behavioral details: compatibility_warning semantics (two cases), temporal_alignment handling, skipped_cross_type/subtype counters, and the explicit warning that pre-mapped topics are often not tradeable. This substantially exceeds annotation coverage 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 long but highly structured (purpose, two modes, response format, safety fields, caveat). Every sentence adds operational value, and the repetition of the topic list mirrors the schema for convenience without being redundant. It is front-loaded with the core purpose.

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

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

With no output schema, the description must explain return values, and it does: 'RESPONSE: each venue's leg-by-leg prices... plus matched spread[].top_spreads_pp.' It also explains safety fields and counter semantics, covering complex edge cases (temporal misalignment, incompatible bet shapes). The tool's complexity justifies this thoroughness.

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

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

All three parameters are documented in the schema with 100% coverage. The description adds the full topic enum list, explains the override semantics of explicit ticker/slug over topic-mapped sides, and clarifies the two modes. This provides additional meaning beyond the schema.

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

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

The description states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the resource and action. It distinguishes from sibling Polymarket-only tools by emphasizing cross-venue comparison and mentions participant pool differences, making the purpose unambiguous.

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

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

The description outlines two usage modes (`topic` shortcuts vs explicit ticker/slug) and cautions that most pre-mapped topics return compatibility warnings, providing clear when-to-use context. It does not explicitly name alternative tools, so it misses the explicit alternatives criterion for 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?

With annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds valuable context about the scoping mechanism (anonymous IP, BYO key hash, account ID) and the pairing with remember/forget. It goes beyond the annotations without contradicting them, though it could detail return format or error behavior.

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

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

The description is efficiently structured in three sentences, front-loading the primary action and immediately clarifying the optional listing behavior. Every sentence contributes to purpose, usage context, or related tools, with no redundant or vague wording.

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 one-parameter tool with robust annotations, the description covers the core purpose, usage scenario, scoping, and related tools. It lacks explicit mention of return values or edge cases, but given the simplicity and presence of annotations, it is sufficiently complete for an agent to select and 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?

The input schema already fully describes the single optional parameter 'key' with the instruction 'Memory key to retrieve (omit to list all keys)' (100% coverage). The description repeats this guidance but does not add new syntax or format details, so it meets the baseline without enhancing parameter semantics.

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

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

The description clearly identifies the tool as a retrieval mechanism for previously saved values, with an explicit action to list all keys when the key argument is omitted. It distinguishes itself from sibling tools by naming 'remember' and 'forget' as complements, making its role unambiguous.

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

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

Provides explicit guidance on when to use the tool: to look up context the agent stored earlier, such as user target ticker or address, without re-deriving. It also names complementary tools (remember, forget) and clarifies scoping to an identifier, effectively outlining the intended usage context and relationships.

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, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing operation. This directly contradicts the readOnlyHint annotation, so transparency score is 1 due to annotation contradiction.

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

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

The description is about 5 sentences but each sentence adds distinct value: purpose, return payload, filtering, mark_read semantics, and an alternative endpoint. It is front-loaded with the main action and avoids 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?

Despite the annotation conflict, the description itself comprehensively covers purpose, return content, filtering options, mark_read side effect, and the alternative HTTP access. With no output schema needed and all parameters described, it is complete for the agent.

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

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

Input schema covers all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds extra context for type (e.g., 'sec_8k'), since (ISO timestamp), and mark_read (flags events read), raising it to 4.

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

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

Description starts with 'Pull fired events from your subscription feed' – a specific verb and resource. It further specifies each event carries source, citation_uri, and raw event payload, clearly distinguishing it from generic list tools like list_recent.

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?

Mentions filtering by type and since, explains mark_read behavior for subsequent calls, and explicitly points to the HTTP endpoint for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools like list_recent, so it provides clear context but no 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?

Discloses rich behavioral details beyond annotations: fan-out to SEC EDGAR, GDELT→GNews fallback, PatentsView API sunset, soft-fail behavior, and output structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). These details align with readOnlyHint and idempotentHint, adding significant context without contradiction.

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

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

The description is longer than average but front-loaded with user-intent examples and structured logically (purpose, sources, fallback, parameters, output, alternatives). Every sentence contributes useful information; the length is justified by the tool's multi-source complexity, though it could be trimmed slightly for better scannability.

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

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

With no output schema, the description fully specifies the return format (changes[], total_changes, citation URIs) and covers edge cases (API sunset, rate limiting, fallback, soft-fail). It also addresses parameter formatting and provides a clear alternative tool, making it self-sufficient 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?

Schema coverage is 100%, so the schema already documents all three parameters clearly. The description adds minor usage guidance (e.g., 'Use 30d or 1m for typical monitoring') but otherwise provides no additional semantic depth beyond what the schema descriptions offer, meeting the baseline for schema-covered parameters.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with concrete natural-language examples ("What's new with X") and explicit scope (filings, news, patents). It distinguishes from sibling entity_profile by noting that the static profile should be used instead, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: it states when to use this tool for time-bounded changes and explicitly directs users to entity_profile for static profiles. It also details fallback behavior (GDELT→GNews, USPTO soft-fail) and gives a concrete recommendation for the `since` parameter ("Use '30d' or '1m' for typical monitoring").

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, but the description adds behavioral context beyond those: key-value scoping by identifier, persistence semantics (authenticated vs anonymous sessions), and retention duration (24 hours). This is useful context that isn't in annotations and helps the agent understand 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 four sentences, front-loaded with the core action, and every sentence carries useful information: what to save, when to use it, storage mechanics, and pairing with recall/forget. No fluff or repetition.

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

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

For a simple two-parameter tool with rich schema descriptions and useful annotations, the description covers the necessary context: purpose, usage timing, storage scope, persistence, and sibling tools. There's no output schema needed, and the description fully equips an agent to invoke it correctly.

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

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

Schema coverage is 100% with well-described key and value parameters, giving a baseline of 3. The description adds extra semantic guidance by illustrating what kinds of data to store (resolved ticker, target address, user preference, research subject) and notes that the key-value pair is scoped by the agent's identifier, which enriches understanding of how the parameters relate.

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: 'Save data the agent will need to reuse later' and clearly distinguishes from siblings by naming recall and forget as complementary tools. It also provides concrete examples (resolved ticker, target address, user preference) that make the purpose unmistakable.

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

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

It explicitly states when to use the tool ('Use when you discover something worth carrying forward') and contrasts it with alternatives by saying 'Pair with recall to retrieve later, forget to delete.' This gives the agent clear decision criteria for when to use remember versus related memory tools.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and that LEI/FIGI enrichment degrades gracefully. It also mentions the cascading internal lookups, adding meaningful 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 detailed but front-loaded with examples and the core purpose. Each sentence adds value, though some redundancy exists between the example list and the subsequent 'SUPPORTED TYPES' explanation. Structure is clear with a dedicated section for types.

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?

Although there is no output schema, the description thoroughly explains the tool's behavior, including fallback mechanisms and the unresolved field, making it effectively complete for an agent to understand inputs and expected outputs.

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

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

The schema already has 100% coverage, but the description adds meaning by explaining what each type returns (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand). It also provides examples for the value parameter, going beyond the schema's simple descriptions.

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

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

The description clearly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and lists example queries. It uses a specific verb (resolve) and resource (entity names to identifiers), distinguishing it from siblings 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. However, it does not name alternatives or exclusion criteria, so it falls slightly short of the highest bar.

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 that the tool internally calls ai_visibility_check for each entity and then ranks by score, which is behavioral context beyond the annotations. It also reveals the output includes a ranked list with score, confidence, and signal density per entity. This adds meaningful transparency about how the tool works, though it does not cover rate limits or permissions, which are adequately addressed by readOnlyHint and other annotations.

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

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

The description is three sentences long, front-loaded with the core action in the first sentence. Each sentence adds distinct value: the first states the purpose, the second explains the process and output, and the third gives a concrete use case. There is no wasted wording 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 tool's moderate complexity (4 params, no output schema, but strong annotations), the description is very complete. It explains the internal mechanism (probing with ai_visibility_check), the output structure (ranked list with score, confidence, signal density), and a practical use case. The schema covers parameters, and annotations cover safety, so the description fills in the remaining process and return-value details effectively.

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

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

The schema provides 100% coverage for all parameters, so the baseline is 3. The description adds no new information about parameters beyond what the schema already includes; it only restates that the first entity is the subject, which is already documented. Therefore, the description provides minimal added value for parameter semantics.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb and resource. It distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and mentions ranking by score and surfacing most/least recognized. The example 'does Claude know about us as well as our competitors?' concretely illustrates the purpose.

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

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

The description explicitly mentions the tool is useful for competitive AI-marketing audits, which provides clear context for when to use it. It implies a comparison use case by stating it probes each entity (brand + N competitors) with ai_visibility_check, subtly differentiating from single-entity alternatives. However, it does not explicitly state exclusions or name alternatives like compare_entities, so it stops short of full when/not guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses composite fan-out across external APIs, potential 5-30s latency on first bundlephobia measurement, and behavior on timeout via 'sources_failed'. This is valuable operational context that annotations alone do not 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?

Every sentence earns its place: purpose, when-to-use, return fields, ecosystem limitation, and latency/failure behavior are all covered. Front-loaded with the core purpose in the first sentence, and the density is appropriate for a composite tool.

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

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

Despite lacking an output schema, the description enumerates all return categories (summary fields, advisory detail, links, alternative versions) and clarifies partial failure behavior. This makes the tool's behavior fully transparent even without structured output definitions.

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

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

Schema already fully documents both parameters with 100% coverage, so the description adds little new parameter-level meaning. It mentions ecosystem scope (NPM only) and version history, but these are more contextual than parameter semantic explanation, keeping it 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?

Description clearly states a composite check for evaluating npm packages, enumerating data sources (deps.dev and bundlephobia) and the exact returned summary fields. It has a specific verb ('check') and resource ('npm package'), distinguishing it from any sibling tool for dependency analysis.

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

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

Explicitly says 'Use whenever an agent asks...' and provides direct alternatives for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also mentions graceful degradation with partial failures, giving clear expectations for when to invoke.

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 the description's additional mention that it returns matching satellites with NORAD IDs and TLE data adds useful behavioral context. This goes beyond the schema 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 a single, front-loaded sentence with no redundant words. It efficiently communicates the core purpose and return 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?

For a simple search tool, the description is quite complete: it states what is searched, what is returned, and the annotations cover safety. An output schema exists, and the description sufficiently explains return values. Minor gaps like pagination behavior are covered by the schema's limit parameter.

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 both parameters (query and limit) are already fully documented. The description adds no additional parameter-specific meaning beyond what the schema provides, meriting the baseline score.

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 searches for satellites by name or keyword, which is a specific verb+resource. It also distinguishes itself from sibling tools like get_tle by indicating it returns matching satellites with NORAD IDs and TLE data, implying search functionality rather than direct 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 implies usage for finding satellites by name or keyword but does not explicitly state when to use this tool over alternatives. No exclusions or alternative tool references are provided, so the guidance is only 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds substantial behavioral context beyond those: top-N passages with character offsets and similarity scores, BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and a 200K char cap with truncation flagging. These details inform the agent about output format and edge cases 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 three sentences, each earning its place: first defines purpose, second gives use case and benefits, third provides technical details and complementarity. It is front-loaded with the core purpose and avoids filler. The structure is easy to parse for an agent.

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 3-parameter tool with no output schema, the description covers the return format (top-N passages with offsets and scores), input constraints (200K cap), use case, and integration with a sibling tool. It provides enough context for an agent to decide when and how to invoke the tool, without needing an output schema.

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

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

Schema coverage is 100% with clear descriptions for all three parameters (text, limit, query). The description reinforces that 'text' is the already-pulled document and 'query' is a natural-language question, but this largely mirrors the schema. It does not add significant new semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states 'Semantic search INSIDE a fetched record' — a specific verb (search) plus resource (inside a fetched record) and scope. It clearly distinguishes from sibling tools like ask_pipeworx_grounded (which grounds over a whole document) and search_satellites (different domain). 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 provides explicit guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit ('saves context, returns only the passages that matter'). It also names a complementary sibling, ask_pipeworx_grounded, and describes how the two tools can be chained ('fetch with the gateway, ground over the relevant passages'). This is clear when-to-use vs. alternatives.

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

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

The description adds substantial behavioral details beyond the annotations: OAuth requirement (anonymous/BYO cannot persist), always-on feed delivery, SMS verification and 10/day cap, webhook HMAC signing and auto-disable after 10 failures. However, it does not clarify idempotent behavior despite idempotentHint=true; the phrase "new subscription id" is ambiguous as to whether duplicate subscriptions are prevented.

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, front-loading the purpose and then systematically covering requirements, types, and delivery options. Every sentence adds value, though the length is considerable; the structure is logical and readable.

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 purpose, all parameters, behavioral constraints, and the return value (subscription id), including the one-time webhook_secret in the response. It lacks a full return object schema, but for a subscription creation tool, the essential information is provided. Given no output schema, the description adequately covers the return.

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

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

Schema coverage is 100%, but the description enriches each parameter with concrete examples (sec_8k items:["5.02"], polymarket_edge topic:"fed") and delivery channel specifics (email, SMS, webhook signing). This goes well beyond the schema's basic descriptions, making parameter usage 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 "Create a proactive monitoring subscription to a live-data event stream," which uses a specific verb and resource, clearly distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also states the return value (subscription id), reinforcing the tool's purpose.

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

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

The description clearly establishes when to use the tool (proactive monitoring) and includes prerequisites (Pipeworx OAuth account, phone verification for SMS). It does not explicitly contrast with one-off data retrieval tools, though the "proactive monitoring" phrasing implicitly differentiates it. This is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds context about the return payload: it returns category-bucketed example questions with exact tool + argument shape drawn from a live catalog, and notes that it is the onboarding entry point—useful behavioral context 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 dense paragraph with multiple examples and details, but every sentence contributes: user queries, return format, parameter behavior, and usage guidance. It is slightly verbose but front-loaded with the most important information, earning a 4 rather than a 5.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shapes) and how to invoke it (no args or with a topic). It also contextualizes when it should be used first, covering both purpose 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?

The input schema fully describes the `topic` parameter with an enumerated list of categories and notes that omitting it gives a cross-category spread, so description coverage is 100%. The description adds only example values ('finance', 'pharma', 'betting') that are already listed in the schema, offering no new parameter semantics; baseline 3 is appropriate.

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

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

The description opens with a range of user phrasing examples ('What can I ask Pipeworx?', 'what is Pipeworx good for?') and clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. This distinguishes it from siblings like discover_tools and ask_pipeworx by specifying its function and scope.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', giving a clear condition for when to use it. It also contrasts with alternatives by mentioning meta-tools (ask_pipeworx, entity_profile, etc.) and provides parameter usage instructions (no args for full spread, topic to focus).

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

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

The description adds meaningful behavioral context beyond annotations: ownership enforcement, row deactivation instead of deletion, and preservation of historical events. This is rich detail that helps the agent understand side effects and consequences.

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 and well-structured: the core action is front-loaded, followed by two sentences that add key behavioral constraints. No filler or redundancy.

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

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

For a simple single-parameter operation with annotations and no output schema, the description covers purpose, ownership, side effects, and data retention. This is complete enough for an agent to use the tool correctly.

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

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

Schema coverage is 100%, with the parameter already described as 'Subscription id (uuid) returned by subscribe.' The description merely restates 'by id' without adding new semantic detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' by using the verb 'cancel'.

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: it's for canceling a subscription, with ownership enforcement ('you can only cancel your own subscriptions'). It does not explicitly name alternatives or when-not-to-use, but the context is sufficient.

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

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

Despite having readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds substantial behavioral context: the existence of two distinct pipelines (SEC EDGAR+ XBRL fast path vs grounded), the verdict enum, the meaning of could_not_verify as a non-evidence error with verification_error, and unsupported as a coverage gap. This goes well beyond annotations.

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

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

The description is dense but well-structured, with a clear intro via natural-language triggers, usage guidance, pipeline breakdown, return format, and important warnings. It is longer than the 2-sentence ideal but every sentence conveys necessary information, and the 'IMPORTANT for callers' section is appropriately highlighted. No wasted words, though it could be tightened slightly.

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, the description is remarkably complete: it explains return values (verdict, actual value, citation, reasoning), distinguishes critical outcomes (could_not_verify vs unsupported), and specifies pipeline routing. There is no output schema, so this description carries the full burden, and it does so thoroughly.

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

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

The input schema covers both parameters with descriptions (100% coverage), so baseline is 3. The tool description adds value by explaining that tolerance_pct overrides the implied tolerance, gives a specific use case (set 1–2 for hallucination detection), and clarifies the default cap of 5. This is beyond schema but not exhaustive.

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 natural-language claim verification against authoritative sources, with explicit phrasing examples and the intended function of returning a verdict. It distinguishes from siblings by emphasizing the fact-checking role with verdicts and pipeline details (SEC EDGAR vs grounded), and notes it replaces 4–6 sequential calls.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger. It also provides nuanced guidance for company-financial claims versus other claims, and explains the meaning of could_not_verify and unsupported. However, it does not explicitly name alternative tools or explicit when-not-to-use scenarios, leaving room for refinement.

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