N2yo

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable behavioral details: default model (Workers AI Llama-3.3-70b), cost implications (BYO Anthropic key, direct payment), and the exact return structure (per-model score, confidence, signals, raw_response + combined view). 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?

Four sentences, front-loaded with the core purpose (probe and score), followed by cost/options and return structure. Every sentence adds essential information with no fluff or redundancy.

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

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

For a read-only tool with no output schema, the description covers purpose, model selection, key handling, cost, and return fields. It is fully sufficient for an agent to select and correctly invoke the tool, especially given the rich annotations and 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics about the models and _apiKey parameters, such as the default model being free and that passing _apiKey enables Anthropic probing with direct payment, which goes beyond the 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's function with a specific verb ('probe'), resource ('one or more LLMs'), and outcome ('score visibility 0-100 per model'). It differentiates itself from sibling tools like ask_pipeworx or deep_research by focusing on visibility scoring rather than general Q&A or research.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly mention when not to use it or name alternatives. This gives clear context 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable behavioral context: it 'fills arguments', returns 'structured answer with stable pipeworx:// citation URIs', and is described as 'one fast call'. This goes beyond the annotations without contradicting them, though it could have mentioned error behavior or rate limits.

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 typical but every sentence earns its place: it covers scope, examples, default status, and alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured with clear directives. A slight reduction in length would improve it, but the richness of guidance justifies the length.

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

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

For a tool that routes to thousands of sources, the description is remarkably complete: it enumerates supported domains, gives example queries, explains the citation mechanism, mentions tier availability and speed, and explicitly contrasts with sibling tools. There is no output schema, so the description carries the responsibility of explaining return behavior, which it does adequately.

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

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

Schema coverage is 100% — all six properties are documented as aliases for 'question'. The description itself doesn't add much about parameters beyond stating that the tool accepts a natural language question and 'fills arguments' internally. The schema provides the necessary detail, and the examples in the schema already cover typical inputs, so a baseline score is appropriate.

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

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

The description clearly states the tool's function: it routes questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It also lists concrete domain examples (SEC, FDA, FRED, patents, etc.) and explicitly positions itself as the default entry point, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description is explicit about when to use this tool versus alternatives: it says to prefer it over web search for factual questions, provides trigger phrases and examples, and gives step-up guidance (use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part queries). It also states it works on every tier and is the default entry point, leaving no ambiguity.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds valuable context: candidate routing improvements are 'enabled live whenever one is under test,' currently none are active, and results are compared against the stable router. This explains the experimental nature and potential behavioral changes beyond what annotations convey.

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

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

The description is four sentences, each contributing relevant information: beta status, identical functionality, current state, usage instruction, and comparison policy. It is front-loaded with the beta identification and is not excessively verbose, though it could be slightly tighter.

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

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

With no output schema, the description compensates by explicitly stating 'same response shape' as ask_pipeworx, allowing the agent to infer return behavior from the stable sibling. It also provides current experimental state and tool count, making it complete enough for a variant tool.

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

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

The schema covers 100% of parameters, with all six listed as aliases for the required 'question' field. The description adds no extra parameter details beyond what the schema already states, so the baseline of 3 applies.

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

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

The description identifies the tool as a 'Beta version of ask_pipeworx: identical universal router' with 5,529 tools, clearly indicating it routes questions to tools. It distinguishes from the stable sibling by mentioning candidate routing improvements and live test status. However, the core action of routing/answering is implied rather than stated with a specific verb like 'routes' or 'answers'.

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

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

The description gives explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router for comparison purposes and clarifies it is not a fallback, eliminating ambiguity about when to choose this over ask_pipeworx.

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?

While annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral context: refusal reasons, verbatim evidence, extraction only from tool results, and the extra LLM call cost. It also details the exact success and refusal response shapes. 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 dense but every sentence earns its place: purpose, mechanism, success output shape, refusal output shape, use cases, and cost trade-off. It is front-loaded with the core value proposition and contains 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?

Given the tool's complexity and the absence of an output schema, the description fully documents the return contract (success and refusal shapes), lists all refusal reasons, and provides guidance on when to use it. It also differentiates from siblings and states cost implications, making it complete for agent decision-making.

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 covers all six parameters (all aliases for the question) at 100% coverage, so the baseline is 3. The description does not add parameter-level syntax or format details; it only explains the routing behavior around the question, which is useful but not param-specific.

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 and scope: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from the sibling ask_pipeworx by explicitly describing the same routing but with extraction only from tool results, and contrasts with the casual variant. This leaves no ambiguity about what the tool does.

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

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

It provides explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on...'), explicit when-not-to-use ('prefer ask_pipeworx for casual lookups'), and names the alternative tool. The cost trade-off (one extra LLM call) further clarifies decision-making.

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

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

The description goes far beyond the annotations by detailing the resolver contract (market_match_confidence, market_match_score, alternatives[], suggestions[]), fan-out logic with examples, safety short-circuit behaviors (low_confidence_match, market_closed_or_inactive), and resolution-rule risk with cancellation_rule values. This provides the agent with rich behavioral context that annotations alone do not cover.

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 exceptionally long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) that make it navigable. Each section adds functional detail, but the density is high and could arguably be trimmed without losing core value, so it earns 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?

For a complex fan-out tool with no output schema, the description covers all critical aspects: parameter formats, classifier categories, fan-out examples, response shapes, resolver behavior, safety statuses, and cancellation rules. This is sufficient for an agent to select and invoke the tool correctly with full awareness of edge cases.

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 documents all three parameters thoroughly (market slug/URL/question text, depth enum with defaults, include_raw default and payload sizes), so schema coverage is 100%. The description does not add new parameter-level guidance beyond restating the market input format, leaving the baseline at 3.

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

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

The description leads with a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then lists explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_arbitrage or deep_research.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not name alternatives or state when not to use it, so it falls short of the highest bar for 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial context beyond that: data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and return format with pipeworx:// citation URIs. No contradiction 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 dense but well-structured. It front-loads example queries and the 'ALWAYS PREFER' directive, then methodically covers data sources, fiscal handling, sorting, and return format. The 'Replaces 8–15 sequential lookups' line adds a useful efficiency cue. Every sentence earns its place.

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

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

For a two-parameter tool with no output schema, the description fully covers invocations (entity types and counts), data sources, output format, and sorting behavior. It also mentions citation URIs per entity, giving agents enough information to select and call the tool confidently.

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

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

The schema already provides 100% coverage with descriptions for both parameters. The tool description adds value by explaining what each type value retrieves (10-K financials vs. FAERS/FDA data) and notes fiscal-calendar nuances. This is above the baseline of 3 but not exhaustive—the 'primary metric' for sorting is not defined explicitly.

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 natural-language triggers and explicitly states the core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' The verb 'compare' is specific, the resource is clear, and it distinguishes itself from sequential single-pack lookups, aligning with sibling context.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives example query patterns and explains the data pulled for each type, making the decision boundary clear. While it doesn't explicitly name a sibling tool, 'sequential single-pack lookups' effectively points to alternatives like entity_profile.

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 context beyond annotations: account/payment requirements, question decomposition into facets, parallel routing to 5,529 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), the never-invents guarantee, semantic excerpting of large records, and expected latency (15-90s). No contradiction with readOnly/idempotent/openWorld hints.

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

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

The description is long but front-loaded with the critical account requirement first, then the core function, then usage guidance, then detailed behavioral semantics. Each sentence adds information, though some trimming of the deeper protocol details could make it more scannable. Still, given the tool's complexity, this length is largely justified.

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

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

For a complex tool with no output schema, the description thoroughly covers return values (findings packet, gaps, contradictions, hop field), limitations (not for breaking news, may return empty gaps), account prerequisites, and expected performance. It is complete enough for an agent to select and invoke the tool correctly without external documentation.

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 elaborates on the depth parameter with concrete meanings (quick=3 facets single hop, standard=5 with gap recovery and contradictions[], thorough=8 paid with iterative hops). It also explains that the question parameter accepts broad/multi-part natural language, which is not fully conveyed by the schema alone.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It clearly distinguishes from siblings by explicitly saying 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups and breaking news.

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

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

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also lists alternatives and even account-tier exclusions ('If you are not signed in, use ask_pipeworx instead').

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, and destructive=false. The description adds meaningful behavioral detail: it returns top-N tools with names, descriptions, and full input schemas with curated examples, ready to call directly with no second lookup needed.

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

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

The description is three sentences, front-loaded with the core purpose and then adding a domain list and call-first guidance. Every sentence provides useful information, and the structure is easy to scan.

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

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

With no output schema, the description compensates by specifying exactly what is returned: tool names, descriptions, full schemas with examples, and direct callability. Combined with strong annotations and clear usage guidance, the description is complete for this meta-tool.

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

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

Schema coverage is 100%, so the schema documents all 6 parameters including aliases and examples. The description adds little beyond stating the query is a natural language description, so it meets the baseline without adding extra parameter insight.

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

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

The description clearly states the tool finds tools by describing data or task, using verbs like browse, search, look up, and discover, and lists specific domains. This distinguishes discover_tools from its research-focused siblings, which are individual data 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 says to use it when needing to browse/search/discover available tools and to call it FIRST when many tools are available and a set of options is needed. It gives clear context but does not name specific sibling tools to prefer instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial context about cross-source fan-out, the exact data returned (CIK, recent filings with URIs, fundamentals, patents, news, LEI), and caveats such as the USPTO PatentsView sunset/soft-fail and GDELT→GNews fallback. This far exceeds what annotations alone provide and contains no contradiction.

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

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

The description is long but dense with valuable information: query examples, source fan-out, return fields, constraints, and failure modes. The front-loaded examples efficiently communicate intent, though the list of example queries is somewhat redundant and could be trimmed without losing substance.

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

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

Given the lack of an output schema and the multi-source complexity, the description provides a thorough inventory of return categories (CIK, recent_filings, fundamentals, patents, news, LEI) and notes important behaviors like 'up to 5' filings, URI format, 'LATEST 10-K', and the patent API soft-fail. This is sufficient for an agent to understand what the tool returns and what limitations exist.

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

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

The schema already covers all parameter semantics at 100% with descriptions for type ('company') and value (ticker or zero-padded CIK, names not supported). The tool description repeats and slightly reinforces these examples ('AAPL', '0000320193'), but it does not add meaningfully new parameter information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states that this tool produces a 'full cross-source profile of a US public company in ONE parallel call' and immediately distinguishes it from chaining single-pack SEC/XBRL/news lookups. It also names concrete user intents ('tell me about X', 'research Acme') and lists specific output components, making the purpose unmistakable and distinct from siblings like resolve_entity.

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 to prefer this tool over chaining lookups when a holistic view is requested, providing a strong when-to-use signal. It also gives a clear alternative: 'names not supported (use resolve_entity first if you only have a name)', which addresses the main prerequisite and fallback path.

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 disclose destructive and idempotent behavior. The description adds context about intended use cases but does not reveal additional behavioral traits like error handling or side effects. It is consistent with annotations, so 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?

Two concise sentences with the core purpose front-loaded. Every word earns its place, providing purpose, usage, and sibling relationships without bloat.

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 delete tool with one parameter, strong annotations, and no output schema, the description fully covers purpose, usage, and positioning. Nothing essential is missing.

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

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

Schema coverage is 100% with a clear description for 'key'. The description adds no new parameter meaning beyond what the schema states, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete'), the resource ('a previously stored memory'), and the method ('by key'). It distinguishes itself from siblings by positioning as the inverse of remember and recall, making its purpose unambiguous.

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

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

Explicitly tells when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, guiding the agent on the tool's role in the memory lifecycle.

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 the description adds that the tool performs a network fetch, extracts specific components, and emits a markdown text blob. This is meaningful behavioral context beyond the annotations, though it does not address error handling or edge cases.

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 tightly written sentences: purpose, process/outcome, then use cases. Every sentence carries weight, with no filler or redundant phrasing. The structure is logical and front-loaded.

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

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

With only two parameters, full schema coverage, and clear safety annotations, the description provides all necessary context: what the tool does, how it works, what it returns, and when to use it. No output schema is present, but the description explicitly states the return format ('single text blob'), which is sufficient.

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

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

The schema provides 100% coverage for both parameters, describing url and max_links in detail. The description's mention of 'key links' and 'link entries' is tangential and adds no semantic value beyond the schema's existing parameter 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 opening sentence clearly specifies the tool generates a production-ready llms.txt file for any URL, and details the process (fetches, extracts, emits) and output format. This is specific and distinguishes it from sibling tools like ai_visibility_check which focus on analyzing AI presence rather than generating a file.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's site. It does not explicitly mention when not to use the tool or name alternatives, which prevents a top score.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations: it specifies the output fields (lat/lon/altitude/look-angles), the 'right now or next few seconds' temporal scope, and the observer-based calculation. 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 two sentences plus a short example. It front-loads the primary purpose and output, then provides a concrete usage example. Every sentence contributes value without redundancy or filler.

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

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

Given the 6-parameter schema with full coverage and strong annotations, this description is adequately complete. It states the return fields (useful because there is no output schema), provides a concrete example, and covers the common use case. It does not explain edge cases (invalid NORAD IDs, rate limits), but that is not essential for a simple read-only lookup 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds an example call and example NORAD IDs, but does not add new semantic meaning beyond what the schema already provides. It does demonstrate parameter usage, which is mildly helpful.

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 ('track'/'get') and clearly identifies the resource ('satellite positions') with concrete outputs (latitude, longitude, altitude, look-angles). It also includes a concrete example (ISS, NORAD 25544), which distinguishes it from sibling tools like get_visual_passes by emphasizing current/now positions.

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

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

It gives clear usage context with 'Use this to answer "where is the ISS right now?"' and explains the general use case (locate any satellite by NORAD id). It does not explicitly mention when not to use it or alternative tools, but the context is sufficient for typical AI selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by detailing the return data (start/max/end times, elevation, azimuths, brightness magnitude, duration) and explaining the visual pass definition, which goes beyond the annotations without contradicting them.

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

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

The description is three concise sentences plus an example, front-loading the core purpose. Every sentence contributes: definition, return values, and a usage example. No redundant or filler 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 appropriately enumerates the returned fields and provides a concrete example. It covers the essential context for a satellite pass query, though it does not address edge cases like no passes found or rate-limit behavior, but those are partially handled by annotations and 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 descriptive parameter definitions. The description complements this by providing a real-world example (ISS with lat/lon) and clarifying the meaning of 'visual passes' in relation to parameters like min_visibility. This adds value beyond the schema alone.

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

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

The description uses a specific verb ('Find') and resource ('satellite visual passes'), clearly defining the scope as naked-eye visibility for an observer location. It distinguishes from sibling tools like get_positions by emphasizing 'bright, sunlit passes against a dark sky' and includes a concrete use case ('when can I see the ISS pass over?').

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

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

Provides a clear use case ('when can I see the ISS pass over?') and a concrete example call, establishing context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, such as differentiating from get_positions or whats_above.

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

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

Annotations declare read-only and idempotent behavior, and the description adds 'caller's active subscriptions' scoping plus a return field list, which goes beyond the structured data. While it doesn't cover potential pagination or edge cases, the core behavior is transparent for a read-only list operation.

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

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

Two sentences: the first states purpose and return fields, the second gives practical usage guidance. Every word earns its place; no filler or redundant 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?

For a simple listing tool with one optional parameter, the description fully covers what it does, what it returns, and when to use it. The output fields are enumerated, and the schema covers the only parameter, so no additional context is 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 include_inactive already described in the schema. The description reinforces the 'active subscriptions' default but adds no new parameter semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb ('List') and explicit resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, making the tool's scope immediately clear.

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

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

The description explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides concrete use cases and implies alternatives (subscribe/unsubscribe), giving clear decision guidance.

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

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

Annotations are neutral (all false), but the description discloses key behavioral traits: rate limiting, the claim_token flow for later retrieval, and that it's free. 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?

Front-loaded with purpose, then usage, exclusions, and token flow. Every sentence is informative, though the roadmap-signal note is slightly extra. Well-structured for a feedback 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?

For a tool with no output schema, it explains the return token, rate limits, and content expectations. It fully covers the feedback workflow and would be clear even without additional schema context.

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

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

Schema descriptions cover all parameters (100% coverage), so baseline is 3. The description adds flow-level meaning by explaining how claim_token is obtained and used, which goes slightly beyond the schema.

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

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

The description clearly states the tool sends feedback to the Pipeworx team, with specific triggers (bug, feature/data_gap, praise). It distinguishes itself from sibling tools by explicitly limiting usage to tools served by this Pipeworx connection, not other MCP servers.

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

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

Provides explicit when-to-use scenarios, when-not-to-use (other vendors' connectors), and an alternative action ('file it with that server instead'). It also gives feedback-writing guidance, such as not pasting end-user prompts, exceeding typical usage notes.

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 valuable behavioral context beyond the annotations: it explains the data source ('derived from CF analytics-engine'), privacy ('no PII'), output structure ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). These details help the agent understand freshness and scope. No contradiction with annotations exists; in fact, the description reinforces the read-only, open-world nature.

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

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

The description is compact and well-structured: one opening sentence defining the tool, a bulleted list of three use cases, and a final sentence covering data provenance and caching. Every sentence carries distinct information, with no redundancy or filler. 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?

For a simple tool with one parameter and no output schema, the description covers the essential elements: what it returns (top tools, packs, call volume), the data format (pack, tool, count), and the time windows. It could specify whether results are sorted or limited (e.g., 'top N'), but given the self-explanatory nature of trending data, the current level is sufficient for an agent to use 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?

The only parameter, `window`, is fully documented in the schema with the same semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The description adds no new parameter-level details beyond what the schema already provides. Since schema coverage is 100%, a 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 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 exact resource (Pipeworx call data), the verb (returns), and the output scope (trending tools/packs/volume). It also distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on aggregated agent behavior rather than individual queries or tool discovery.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming a canonical tool, and checking use-case alignment. This gives clear context for when to use the tool. It does not explicitly name alternative tools or state when not to use it, but the use cases provide sufficient guidance for a simple read-only analytics tool. The window-selector guidance also helps choose between 24h/7d/30d.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing internal logic: semantic anchor Jaccard threshold (≥0.30), partition placeholder filter (>20% returns null), fill-check behavior (realizable_edge_pp ≤ 0 means do not trade), and the response structure. It even explains skipped_low_similarity and thin_legs, providing a comprehensive behavioral profile. 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 dense and long, but every section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) adds unique, necessary information. It is front-loaded with a clear summary and mode breakdown. However, it could be tightened slightly (e.g., repeating 'event' and 'topic' definitions) without losing value, so it earns 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 having no output schema, the description fully explains the response structure (opportunities[], partition_check fields, fill-check results). It covers edge cases (null signal, skipped_low_similarity, placeholders), behavioral thresholds, and cross-mode details. For a complex tool with multiple modes and checks, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: event accepts slugs or full URLs, topic expects seed questions, and the description explains exactly how each parameter affects mode behavior. It also clarifies that no arguments triggers trending_scan. This elevates the parameter semantics well beyond the baseline.

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

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

The description starts with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges by focusing on arbitrage through structural checks. The three modes (trending_scan, event, topic) are explicitly described, making the tool's purpose unmistakable.

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

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

The description provides explicit usage guidance: call with no args for a trending scan, pass event for a specific market, pass topic for cross-event scanning. It recommends 'event (recommended for a specific market)' and explains what cross-event mode catches that single-event misses. It also points to an alternative tool for custom sizing (polymarket_fill_risk), satisfying the when-to-use vs alternatives criterion.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: cached 1h at the KV level, slippage handling, Kelly caps, model-specific details (e.g., per-sport α coefficients), diagnostics for empty segments, and the Fed note. This goes well beyond the annotations and provides deep transparency into how the tool behaves.

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 it is densely packed with unique information—model families, coefficients, caveats, diagnostics—and every sentence contributes. It is front-loaded with the purpose statement, though the single-paragraph structure could be improved with bullet points or clearer sectioning. Given the tool's complexity, the length is appropriate and not wasteful.

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

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

With 9 parameters, no output schema, and high complexity, the description thoroughly covers the response structure (by_segment, fed_candidates, _diagnostics), model families, limitations (Fed signal unreliability), and practical knobs. Agents can fully anticipate what the tool returns and why segments might be empty, making the description complete for its complexity level.

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

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

The schema has 100% parameter description coverage, so the structured fields already explain each parameter. The description adds value by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining nuanced behaviors like how min_partition_leg_kelly applies to basket trades when parent-level Kelly is zero. This additional semantic context justifies a score above the baseline of 3.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It provides a specific verb (scan/return), resource (Polymarket markets), and differentiates itself from siblings by emphasizing Pipeworx data and three model families. The use case 'what should I bet on today' further clarifies the intended 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 states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs and the fed-note caveat, providing clear context for when to use the tool. However, it does not explicitly name alternatives or exclusion criteria, 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds significant context beyond that: snapshots are written on cache-miss (so gaps mean no scan), history bounded by 60-day TTL, decay computed from daily closes not intraday, and response contains lifespan data. 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 dense but well-structured: purpose, key question, args, response fields, and limitations in clear sections. Every sentence adds value, though slightly long; front-loaded with 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 fully documents the response structure (tracked, expired, snapshot_dates), first_seen, trend, decay_per_pp_per_day, lifespan_days, and limitations. This is complete for a tool of moderate 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?

Input schema covers 100% of parameters with descriptions (days lookback clamp 2-30, window family). The description restates defaults and adds 'snapshot family' interpretation, but no additional syntax or format details beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool tracks 'edge persistence and decay' built from 'daily polymarket_edges snapshots,' with the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) and other Polymarket 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 provides usage context: 'a fresh wide edge and a 3-week-old wide edge are different trades' and 'the median lifespan is your competition clock.' It implies this tool is for assessing edge age/decay before trading, though it doesn't explicitly contrast with alternatives by name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is given. The description adds substantial behavioral detail: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), handles defaults and clamping, and warns about thin_legs and forced_directional_risk—all beyond what annotations provide.

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

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

The description is a dense single paragraph, but it is well-structured with clear mode separators (SINGLE-MARKET: / BASKET:) and a final usage directive. It is longer than average, but every sentence carries critical information for a complex two-mode tool, so the length is justified.

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

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

Given the tool's complexity and lack of an output schema, the description must explain return values, and it does: it lists all key outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc. for basket). It also covers parameter semantics, edge cases, and the practical risk of partial fills, making it 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?

Schema coverage is 100%, so the baseline is 3, but the description enriches parameter meaning significantly. It explains mode-specific interpretations (e.g., size_usd means 'max spend on buys' in single-market but 'settlement notional S (shares per leg)' in basket mode), defaults ('default buy_yes', 'default auto'), and the clamp range. This goes well beyond the schema's per-parameter 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely identifies the tool's function and resource. It clearly distinguishes two operating modes (single-market and basket) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why this tool should be used first, citing the risk of unhedged directional positions from partial fills, which serves as a clear when-not condition.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.) by disclosing conditions for compatibility_warning, temporal_alignment, and skipped_cross_type counters. It transparently explains what happens when bet shapes are non-equivalent and warns about misleading spreads, all without contradicting the annotations.

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

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

The description is long but dense, with every sentence providing operational detail. It is front-loaded with the core purpose, then covers modes, response format, safety fields, and a caution. While it could be slightly trimmed, the structure is logical and the length is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly explains the response structure including leg-by-leg prices, top_spreads_pp, and safety fields. It also covers edge cases like temporal misalignment and skipped cross-type comparisons, making it complete for an agent to understand the data it will receive.

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

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

Schema coverage is 100%, so parameters are already described, but the description adds meaningful semantics: it explains the role of 'topic' as pre-mapped shortcuts, how explicit tickers override the mapped side, and provides concrete examples. This adds value beyond the schema's property 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is specific about the two venues and the concept of equivalent bet shapes, distinguishing it from sibling tools like polymarket_arbitrage.

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 explains two modes (topic shortcuts vs explicit ticker/slug pairings) and provides strong guidance on when to expect compatibility warnings, emphasizing that most pre-mapped topics are not tradeable. This gives clear direction on when to use the tool and its limitations.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by disclosing scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-keys behavior. This goes beyond the annotations and provides useful operational 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?

Three sentences, all essential, with the primary action front-loaded. The description efficiently covers behavior, usage context, scoping, and related tools without redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is sufficiently complete: it explains the main retrieval action, the listing alternative, scoping, and complementary tools. It doesn't specify return value format on not-found, but this is minor for a simple memory read.

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

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

The schema already covers the single parameter with a clear description. The description reinforces this by explaining the omit-to-list behavior and providing concrete examples of key values (user's target ticker, address, research notes), adding semantic richness 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 verb and resource: 'Retrieve a value previously saved via remember.' It clearly distinguishes dual behavior (retrieve specific key or list all keys) and names sibling tools (remember, forget), making the tool's function 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?

Explicit guidance is given: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It explains how to list all keys by omitting the key argument and notes scoping to identifier. It doesn't explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds context about the return payload, mark_read side effect, and that polling works fine. No contradiction with annotations; the mark_read write is clearly disclosed.

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

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

Three sentences, each earning its place: purpose and return fields, filtering options, and state behavior plus alternative endpoint. No filler and front-loaded.

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

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

Despite no output schema, the description covers the essential return structure, filtering, state mutation, and even an alternative access method. The unread_only parameter is left to schema but that's covered.

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

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

Schema already documents all 5 parameters at 100% coverage. The description adds practical meaning: type example, ISO timestamp for since, and mark_read's effect on subsequent calls, adding value beyond schema.

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

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

Description clearly states it pulls fired events/alerts from the subscription feed and lists the exact data fields returned (source, citation_uri, raw event payload). It distinguishes itself from sibling subscription management tools by focusing on reading alerts rather than managing subscriptions.

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

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

Provides concrete filtering guidance (type, since), explains mark_read behavior for advancing the feed, and notes polling is acceptable. Also points to an alternative HTTP endpoint for scripts, but doesn't explicitly state when to prefer 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 readOnly, idempotent, openWorld, and non-destructive, and the description adds substantial behavioral context: parallel fan-out to three sources, source-specific data (filings, news, patents), GDELT→GNews fallback on rate limiting/5xx, PatentsView sunset soft-fail, and the output shape (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is dense but not bloated. It front-loads user-facing examples, then delivers technical details in a single flowing paragraph. Every sentence contributes (sources, fallback, sunset note, syntax, output, alternative tool). Slightly long, but appropriate for the tool's complexity; a structured list would improve skimmability.

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

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

With no output schema, the description carries full responsibility for explaining returns—and it does: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers input formats, source behavior, failure modes, and the key alternative, making it complete for an agent to select and invoke successfully.

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, but the description adds source-level meaning beyond schema: `since` controls the window for filings, news mentions, and patent grants; `value` maps to ticker or CIK; `type` is restricted to 'company'. The description does not merely repeat schema—it explains how each parameter drives different upstream APIs, which is useful semantic 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 natural-language queries and then states the core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the resource (company changes over time), the aggregation across SEC, news, and USPTO, and differentiates from the sibling entity_profile by explicitly naming that alternative for static profiles.

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 strong usage guidance: example queries ('What's new with X', 'updates on Acme'), the window parameter semantics, and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT→GNews), which helps agents decide when this tool is appropriate.

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 annotations already covering idempotency and non-destructiveness, the description adds valuable behavioral context: storage as a key-value pair scoped by identifier, persistence differences between authenticated and anonymous sessions (24 hours), and relationship to related tools. This goes beyond the annotation metadata.

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, leading with the core purpose, then usage guidance, then behavioral details, and ending with tool relationships. Every sentence earns its place with actionable information and no redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description covers all necessary aspects: purpose, usage scenarios, storage semantics, persistence expiration, and inter-tool operations. It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

The input schema already provides 100% coverage with clear descriptions and examples for both key and value. The description reinforces these examples but does not add significant new semantic detail beyond what the schema already conveys. It meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function with a specific verb ('Save data') and resource ('data the agent will need to reuse later'). It distinguishes from siblings by mentioning 'across this conversation or across sessions' and explicitly names related tools (recall, forget) for retrieval and deletion.

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

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

The description provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains why ('so you don't have to look it up again'). It also gives usage context by pairing with recall and forget, making the decision tree 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: identifiers are source-labelled, unresolved identifiers are explicitly listed under an `unresolved` field, and LEI/FIGI enrichment degrades gracefully. This is rich transparency for a complex lookup tool.

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

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

The description is lengthy but well-structured, starting with example queries, then a clear core statement, and a structured breakdown of supported types. All content adds value, though the opening example list is somewhat extended. It remains front-loaded and scannable.

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

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

With no output schema, the description carries the burden of explaining return values. It does so thoroughly: for company, it mentions CIK, ticker, company_name, LEI with ownership, and FIGI; for drug, RxCUI, ingredient, brand, and a citation. It also covers fallback behavior and unresolved field semantics, making the tool's behavior complete despite missing 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%, so the baseline is 3. The description enriches parameter understanding by detailing what each type returns (e.g., CIK, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and clarifying accepted inputs (ticker, CIK, or company name). This exceeds the schema's basic definitions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers used by other tools. It provides concrete example queries and specifies two entity types ('company', 'drug'), distinguishing it from sibling tools. The phrase 'Use FIRST whenever you have a name but need an ID' explicitly positions it relative to 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?

The description gives explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and explains its efficiency advantage ('replaces 2-3 manual lookups'). It does not explicitly name alternative tools or say when not to use it, but the 'first step' framing makes the intended usage clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating that it probes each entity via ai_visibility_check, ranks by score, and returns a specific structure (score, confidence, signal density). This goes beyond the schema and annotations, enhancing transparency.

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

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

Four concise sentences, front-loaded with the primary action, followed by mechanism, use case, and output format. Every sentence adds distinct value without redundancy or fluff, making it efficiently 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?

Given that the tool has no output schema, the description's inclusion of the return structure is essential and covered. The schema fully documents parameters, and annotations cover the safety profile. The description is missing only minor details like default model behavior (which is in the schema) and potential rate limits, but overall it is complete enough for a read-only comparison tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only marginal semantic context for parameters (e.g., "your brand + N competitors" clarifies the entities param) but does not enhance understanding of models, _apiKey, or context beyond what the schema already states. The schema carries the burden, and the description's contribution is minimal.

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: "Compare AI visibility across multiple entities side-by-side," and clearly differentiates itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking. It also states the output type (ranked list with score, confidence, signal density), leaving no ambiguity about what the tool accomplishes.

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

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

The description gives a concrete use case ("competitive AI-marketing audits") and an illustrative question, which clearly tells when to use it. It does not explicitly state when not to use it, but the "side-by-side" scope vs. single-entity probe is implicit, so the guidance is clear but lacks explicit exclusions.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavioral traits: composite fan-out across multiple APIs, graceful degradation on partial failures, potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. This is rich behavioral context that annotations alone do not provide.

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

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

The description is relatively long but every sentence adds value: it explains the composite nature, lists what it returns, gives usage triggers, states ecosystem limitations, and warns about timing. The structure is logical with clear sections. Slightly verbose for a tool description, but not wasteful.

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

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

Given the tool's complexity (composite with multiple sources, partial failures, many return fields), the description is very complete. It details the return summary fields, mentions per-advisory details and links, notes ecosystem scope, and explains failure behavior. No output schema exists, so the description carries the full burden—and it succeeds.

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 full descriptions for both parameters (package and version), with 100% coverage. The description does not add significant new meaning about parameters, except reinforcing that 'package' is an npm package name and that the 'NPM ecosystem only' scoping applies. The baseline score of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It specifies the exact resources and data points (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), distinguishing it from any 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?

The description explicitly states when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear usage guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds significant detail beyond that: specific embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), and the 200K char cap with truncation+flag behavior. This goes well beyond the structured fields, giving agents a clear model of operational 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 compact but information-dense. Each sentence serves a distinct purpose: the first explains core function, the second gives usage rationale, the third provides workflow pairing, and the fourth offers technical details. No fluff, well structured, and front-loaded with the core action.

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

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

Given there is no output schema, the description adequately describes return format ('top-N passages with character offsets and similarity scores'). It also covers edge cases (truncation, flagging) and algorithm behaviors. The description is complete for a moderately complex tool with 3 parameters and no 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 already covers all 3 parameters with clear descriptions (100% coverage). The description adds contextual meaning by explaining the search algorithm and output format (character offsets, similarity scores), but does not elaborate on the limit parameter beyond what the schema states. Slight value-add over schema, hence 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 immediately states 'Semantic search INSIDE a fetched record', naming a specific verb ('search'), a specific resource ('fetched record'), and the scope ('inside'). It clearly distinguishes itself from sibling tools like ask_pipeworx_grounded by positioning as a component of a larger workflow ('Pairs with...').

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

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

The description provides explicit 'when' guidance: 'Use when the record is too big to cram into the prompt'. It also names a direct alternative workflow, ask_pipeworx_grounded, explaining how the tools complement each other ('fetch with the gateway, ground over the relevant passages').

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds useful context beyond annotations: OAuth requirement, feed always on, SMS verification and daily cap. However, it omits the webhook delivery channel entirely, including its HMAC signing and auto-disable behavior, which are significant behavioral traits. 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 dense but well-structured, front-loading the purpose, return value, and key constraints in three sentences. Each clause adds value, though it is slightly long and omits webhook while including some info also present in the schema. No fluff, but not maximally concise.

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

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

With no output schema, the description must explain return values, and it does ('Returns the new subscription id'). It covers auth, types, and delivery channels. However, it fails to mention the webhook channel and its one-time signing secret, which are important for agents choosing delivery options. Given the schema's richness, the description is not fully complete but covers most essential operational aspects.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic meaning beyond the schema by explaining real-world examples: 'items:["5.02"] = officer change', 'Polymarket↔Kalshi cross-venue mispricings', and 'fred_series (new FRED observations)'. These enrich the parameter understanding beyond the terse type-specific filter descriptions in the schema.

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

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

The description clearly states the verb ('Create'), the resource ('a proactive monitoring subscription'), and the domain ('live-data event stream'). It also mentions the return value (subscription id) and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides clear context for when to use the tool: to create persistent subscriptions for specific live-data types. It explicitly notes the auth requirement ('anonymous + BYO cannot persist subscriptions') and names delivery channels, with an alternative for pulling feed data via recent_alerts. However, it does not explicitly state 'use list_subscriptions to view existing' or 'use unsubscribe to remove', so exclusions/alternatives are only partially covered.

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 behavioral context beyond the annotations by describing the output structure (category-bucketed example questions with tool+argument shapes) and input flexibility (no args for full spread or topic to focus). Annotations already declare readOnly/openWorld/idempotent, so the bar is lower; the added detail is valuable but not exhaustive.

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

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

The description is fairly long but information-dense, opening with user queries and then clearly stating purpose, output, and usage. While every part earns its place, it could be tightened without losing key details.

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

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

With no output schema, the description compensates by explaining the return value (category-bucketed example questions with tool+argument shape) and covers the single input parameter. It also addresses the onboarding use case, making it complete for the tool's purpose.

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 documents the `topic` parameter with allowed values and the effect of omitting it (100% coverage). The description only adds examples like 'finance' and 'pharma' without new meaning, 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 returns category-bucketed example questions with exact tool and argument shapes, and positions it as the onboarding entry point. It distinguishes itself from sibling meta-tools by instructing the agent to use it first to learn how to call them.

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 directs the agent to use this tool first when it does not yet know what Pipeworx can do, and mentions learning how to call meta-tools. This gives clear when-to-use guidance and implies alternatives, satisfying the dimension.

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 signal mutating, non-destructive, idempotent behavior. The description adds substantive context beyond annotations: ownership enforcement, row deactivation instead of deletion, and the availability of historical events via recent_alerts. This enriches the tool's behavioral profile without any 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 three sentences long, all content-bearing, with no filler. It front-loads the core action, then explains constraints and side effects efficiently.

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 mutation with no output schema, the description covers the key aspects: input, ownership, side effect (deactivation), and downstream availability of historical data. It is complete enough for an agent to invoke correctly without further guidance.

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 only parameter 'id' (subscription id returned by subscribe), covering 100% of the schema. The description adds no new param-specific detail beyond what the schema provides, 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'), the resource ('a subscription'), and the method ('by id'). It explicitly differentiates from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and the ownership enforcement adds a unique 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 provides clear context for when to use the tool (to cancel a subscription you own) and includes behavioral details like ownership enforcement and deactivation. However, it does not explicitly name alternative tools or state when not to use it, which would earn 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 (readOnly, openWorld, idempotent, non-destructive), the description discloses the full verdict set, the critical distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covered), and the dual structured/grounded pipeline. This is rich behavioral context that prevents misuse.

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-organized: query examples, use-case, pipeline details, return value, and important caller warnings. Every sentence serves a purpose, though a slight tightening could remove redundancy (e.g., 'authoritative sources' and 'grounded pipeline' are mentioned separately). Still, for the complexity, it is appropriately concise.

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

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

With no output schema, the description fully explains return values (verdict, actual value with citation, reasoning), clarifies two ambiguous verdicts, and describes both execution paths. It also notes the tool replaces multi-step calls, giving a complete picture of what the agent can expect and how to interpret results.

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

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

The input schema already provides complete descriptions for both parameters (claim and tolerance_pct), including examples and defaults, so schema coverage is 100%. The description adds no additional parameter-level detail beyond the schema, which warrants the baseline score of 3.

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

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

The description opens with direct natural-language examples ('Is it true that…', 'fact check', 'verify the claim that…') and defines the resource: natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by focusing on checking the factual correctness of user claims and even mentions it replaces multiple 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details two execution paths (SEC EDGAR for company-financial claims, grounded pipeline for all others), which helps the agent anticipate behavior. However, it does not name alternative tools or state explicit when-not-to-use conditions, 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the radius and category filter behavior but does not disclose potential quirks like API rate limits or response size. It does not contradict annotations, so a mid-range score is fair.

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 concise sentences plus a short example call. It front-loads the core action, includes the intended use, and provides a concrete invocation. Every part earns its place with no filler.

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

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

For a read-only list tool with 6 well-documented parameters and no output schema, the description gives enough context to invoke correctly: purpose, scope, optional filtering, and an example. It doesn't explain the return format in detail, but 'List what satellites' implies a list of satellite objects, which is reasonable without an output schema. Minor gap but overall sufficient.

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

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

Schema description coverage is 100%, so all parameters are documented structurally. The description adds examples (e.g., category 52 = Starlink) and an example call, which is helpful but not essential given the schema. It does not introduce meaning beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb ('List') and a clear resource ('satellites currently above a location on Earth'), and further scopes it by 'within a given radius of the observer's zenith.' This clearly distinguishes it from siblings like get_positions or get_visual_passes. The example call reinforces 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?

It explicitly states the intended use case ('Use this to answer "what satellites are overhead right now?"') and shows a concrete example. It does not explicitly list when not to use it or name alternatives, but for a simple query tool, the context is clear enough. A 4 is appropriate for clear context without exclusions.

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