geo

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses important behavioral traits: it calls external LLM APIs, mentions the cost implication for Anthropic ('BYO key — you pay Anthropic directly for those calls'), and specifies the return structure. This adds valuable context over the annotations, though it remains silent on rate limits or latency, so it doesn't earn a 5.

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, then providing key details (default model, cost, output format) and usage scenarios. Every sentence contributes meaning, with no fluff or repetition of schema fields, making it highly concise and well-structured.

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

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

Given the tool's complexity (4 params, no output schema), the description adequately covers the return structure ('{score, confidence, signals, raw_response} + a combined view'), default behavior, and cost implications. It lacks explicit alternatives or exclusions, which are partially addressed in usage guidelines but not in the description, so it is not maximally complete but still robust for 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 four parameters with descriptions (100% coverage), so the baseline is 3. The description adds a little by explaining the default model and that _apiKey is needed for Anthropic, but it does not substantially enhance parameter understanding beyond the schema. It correctly reinforces the behavior without introducing new parameter-level detail.

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 specific verbs and resources: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It also enumerates concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and distinguishes itself by detailing per-model scoring and the combined view, which differentiates it from sibling tools like scan_competitor_ai_presence.

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 ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes the default model and optional Anthropic key. However, it does not explicitly name alternatives or mention scenarios where a different sibling tool would be more appropriate, so it lacks the exclusionary guidance that would make it a 5.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds meaningful behavioral context: the tool acts as a router, automatically fills arguments, and returns answers with stable pipeworx:// citation URIs. It also mentions that it covers 5,596 tools across 1,465 verified sources, which sets expectations about its breadth. There is no contradiction with the annotations.

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

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

The description is long, but the breadth of the tool justifies it. It front-loads the most important signal ('PREFER OVER WEB SEARCH') and then organizes the content into purpose, usage, examples, and alternative routing. Some redundancy exists in the long list of data categories and the exact phrasing of examples, but nearly every sentence contributes to selection accuracy.

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

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

For a tool with one required parameter, no output schema, and no nested objects, the description fully covers the necessary context: when to use it, what to feed it (examples and trigger phrases), what it returns (structured answers with citations), and when to use siblings instead. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%; `question` is well documented as a natural-language query accepting aliases such as q, query, prompt, text, and input. The description adds value by giving concrete example questions and defining the expected input as fact-oriented real-world queries, which goes beyond the baseline schema description. The single parameter is therefore clear.

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

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

The description clearly defines the tool's purpose: it routes a natural-language factual question to an appropriate tool among 5,596 tools across 1,465 verified sources, fills arguments, and returns a structured answer with pipeworx:// citations. It also distinguishes itself from deep_research, validate_claim, resolve_entity, and web search, so an agent can easily recognize when this specific tool is relevant.

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

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

The description provides explicit use guidance: 'PREFER OVER WEB SEARCH' for a long list of fact-oriented categories, and it gives trigger phrases ('what is', 'look up', 'find', 'get the latest') plus examples. It also names alternatives for specific cases: use deep_research for a single deep authoritative answer, validate_claim for claim validation, and resolve_entity for entity resolution. This is exactly the when-and-when-not guidance needed.

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 meaningful behavioral context: it is a live experimental router, candidate improvements are tested in production, no candidate is currently active, and it is a fully working router—not a stub or fallback. This goes well beyond structured annotations and informs the agent about dynamic 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 concise, front-loaded, and every sentence provides relevant information: identity, current state, usage, history, and reassurance it is a full router. A minor amount of redundancy (the concept of 'newest routing' appears multiple times) prevents a perfect score.

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

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

Given the simple single-required-parameter interface and 100% schema coverage, the description adequately covers what the agent needs: what the tool is, current routing status, that it matches ask_pipeworx, and that it expects the same arguments. It does not detail the response shape, but claims 'same response shape' as ask_pipeworx, which is sufficient for this domain.

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 each parameter described and 'question' documented as accepting aliases. The description adds only 'same arguments' without detailing parameter specifics, so the schema carries the necessary meaning. Baseline 3 is appropriate since the description adds no meaningful semantic value beyond the schema.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router', which clearly identifies the tool as a router accepting natural-language questions and resolving to one of 5,596 tools. It distinguishes this beta from the stable ask_pipeworx by noting it is an experimental edge with live candidate routing improvements. It relies on ask_pipeworx as the main reference point, but the purpose is specific and unambiguous.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router to decide merges, which helps an agent reason about when selecting this beta vs stable. This is strong, actionable usage direction.

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

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

Beyond the read-only/idempotent annotations, it discloses the full behavioral contract: success returns answer, evidence, confidence, source, fetched_at; failure returns an explicit refusal with specific refusal reasons. This tells an agent exactly what happens when the answer is unavailable.

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 the high-level purpose, then provides the output/refusal contract, the exact comparative cost, and a selection rule. Every sentence contributes operational value without 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 complex tool operating over thousands of sources, the description gives the runtime behavior, refusal semantics, expected usage context, and tradeoff vs. the sibling tool. The parameter side is fully handled by the schema, and the absence of output schema is compensated by documenting the return shape in the 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?

The input schema has complete 100% coverage, describing the question field and its aliases. The description adds no parameter-specific meaning beyond the schema because it focuses on behavior rather than telling the agent how to phrase or format the question.

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

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

The description clearly identifies a hallucination-resistant, grounded answer mode that extracts answers using only the tool result. It explicitly traces the same routing as ask_pipeworx, which distinguishes this tool from the sibling ask tools and gives a precise operational 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 says exactly when to use this tool: when the answer will be quoted, cited, or acted on, and the agent must not invent facts. It also states a clear alternative — prefer ask_pipeworx for casual lookups — and justifies it by the extra LLM call cost.

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

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

The description goes far beyond the annotations by detailing resolver confidence levels, low-confidence short-circuit behavior, closed-market status, wide-spread tradeability warnings, and cancellation-rule risk. It even explains the blocking routes for de-indexed markets. This is extensive behavioral disclosure beyond the readOnly/idempotent 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 well-structured with CAPS topic headers (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.), front-loading the core purpose and input examples. While every section is relevant, some redundancy exists (e.g., low-confidence behavior appears in both SAFETY and RESOLVER CONTRACT), but overall it earns its length for a complex 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?

There is no output schema, so the description must carry the full burden of describing the response. It does so exhaustively: market fields, analysis fields (including warnings), evidence keying, resolver contract, parent_event partition data, news backfill status, and cancellation-rule semantics. It also covers safety paths and blocking behaviors, making it complete for an agent to use safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces accepted formats but adds little beyond the schema's own parameter descriptions (e.g., the market property already lists examples). The discussion of depth and include_raw effects is already present in the schema, so the description contributes marginal extra value.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on research/fan-out. The scope (slug/URL/question text to evidence packet) is 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 usage triggers are given ('Use for "should I bet on X"...'), and the fan-out examples illustrate appropriate contexts. However, it does not explicitly mention when not to use it or name alternative sibling tools, so while context is clear, there are no stated exclusions.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: data sources and specific metrics for each type, handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, return of paired data with pipeworx:// citation URIs, and the efficiency claim (replaces 8–15 sequential lookups). This goes well beyond the annotation 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 dense but well-structured, front-loading trigger phrases and the core purpose. It includes examples and specific details without unnecessary fluff. While it is longer than some tool descriptions, every sentence adds value—trigger patterns, usage directive, data sources, fiscal year edge case, sorting, and return format. Minor redundancy in listing multiple trigger phrases is acceptable for NLP-oriented tools.

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

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

Given the tool's complexity (two entity types, multiple entities, varied data sources, sorting, citations) and lack of an output schema, the description adequately covers all critical aspects: what data is returned, how it is sorted, and how results are formatted with citation URIs. The mention of fiscal year handling and the efficiency benefit further round out the context. No significant gaps remain.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds extra meaning by explaining what each 'type' value retrieves (latest 10-K revenue/net income/cash/long-term debt vs. FAERS adverse-event counts, FDA approvals, active trials) and gives examples for the 'values' array (tickers/CIKs for companies, names for drugs). This enhances parameter understanding beyond the schema baseline.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific action verbs ('compare', 'rank') and gives concrete trigger examples, distinguishing itself from sequential single-pack lookups. The scope is well-defined with type-specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs).

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

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

The description explicitly states when to use the tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides natural-language trigger patterns ('X vs Y', 'which is bigger') and clarifies the context for both entity types. This effectively guides the agent to use this tool for comparison tasks instead of alternative lookups.

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

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

Annotations already mark read-only, open-world, idempotent, non-destructive; the description adds substantial contextual behavior on top: required sign-in and paid tier for 'thorough', parallel decomposition across 5,596 tools, never-invented gaps[], contradictions[] in standard/thorough, semantic excerpting, citation fetchability, and 15-90s latency expectations. Rich and additive — no contradiction with annotations.

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

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

The description is long but every sentence carries distinct, decision-relevant information — auth constraint, fallback routing, scope, decomposition mechanics, return packet shape, gap behavior, pricing, latency. It is front-loaded with the critical account requirement. A more compact formatting with fewer bolding artifacts would be even better, but there is no filler.

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

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

Despite having no output schema, the description fully covers return shape (findings packet: evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[], contradictions[]), timing, prerequisites, and limitations. Everything an agent needs to select, invoke, and interpret the result correctly is present.

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 practical value beyond the schema: it clarifies that 'thorough' requires a paid plan, explains what each depth hop does behaviorally (gap recovery, contradiction scan), and gives examples of questions well-suited to the free-form 'question' param. This justifies one point above baseline.

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

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

The description names a specific verb and resource: grounded multi-source research across Pipeworx's 1465 structured data sources in one call. It distinguishes itself from both ask_pipeworx and open-web search, and gives concrete question examples ('compare X and Y's regulatory + financial exposure'), so an agent can unambiguously identify its niche.

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 present: broad/multi-part questions over structured data, with examples. Explicit routing to the alternative: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' No ambiguity about when this tool should be selected.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by describing the delivered output and its direct-callability. It doesn't cover rate limits or auth, but that's acceptable given the read-only 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 front-loaded: first sentence states the core function, second lists covered domains, third explains return behavior and usage priority. Every sentence contributes; the domain list is useful for scope. No redundancy or filler.

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

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

For a tool discovery meta-tool with no output schema, the description covers purpose, usage context, return format, and placement in a multi-tool environment. It provides enough information for an agent to decide to invoke it and know what to expect. The absence of an output schema is compensated by describing the result contents.

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 3 applies. The query field's schema description is rich (accepts aliases, examples). The tool description adds 'by describing the data or task' which aligns with the query semantics but doesn't provide additional meaning beyond the schema. No further parameter details are necessary because the schema fully documents them.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates specific domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes this meta-search tool from sibling data tools by positioning it as a discovery layer that returns tool options. The verb+resource structure ('find tools') is specific and clearly differentiates it from siblings like compare_entities 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?

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This conveys both when to use and when not (when you already know the exact tool). Although no sibling alternative is named, the conditional guidance is clear and actionable.

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

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

The description adds substantial behavioral context beyond the annotations: 'Fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF,' 'in ONE parallel call,' notes the USPTO API sunset with 'soft-fails until reactivated,' and explains GDELT→GNews fallback. These details reveal operational behaviors (parallelism, resilience) not captured by readOnlyHint/idempotentHint.

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

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

The description is a single dense paragraph but organized with a clear flow: example queries, usage guidance, fan-out details, return fields, and input requirements. It is longer than typical but each section contributes essential information; however, it could be slightly more structured with bullet points or separate sentences for easier parsing.

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

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

Despite no output schema, the description fully enumerates the return fields (cik, company_name, recent_filings with URIs, fundamentals specifics, patents status, news fallback, LEI). It also covers limitations (names unsupported) and extra context (patent API sunset), making it complete for a complex multi-source tool.

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

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

The input schema already provides descriptions for both parameters with examples ('AAPL', zero-padded CIK) and explicitly states name unsupported. The description repeats this almost verbatim, adding no incremental semantic value. With 100% schema coverage, 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 this tool builds a full cross-source profile of a US public company, with specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes itself from siblings by emphasizing the 'ALWAYS PREFER' directive for holistic views, differentiating it from single-pack lookups or tools like compare_entities and 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This directly steers the agent toward alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the mechanism ('by key') but doesn't disclose failure modes or permanence beyond what annotations imply. Some added context, but limited.

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 short sentences front-load the purpose, provide usage guidance, and mention sibling pairing. No filler or redundancy.

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

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

For a simple one-parameter tool with strong annotations and no output schema, the description covers purpose, usage conditions, and relationships to siblings. No critical information is missing.

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

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

Schema covers the single 'key' parameter with a clear description ('Memory key to delete'), and the description's 'by key' adds no further semantic detail. High schema coverage justifies baseline 3.

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

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

The description states a specific verb ('Delete'), resource ('previously stored memory'), and method ('by key'), clearly distinguishing it from sibling tools like remember and recall.

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

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

Provides explicit use cases ('context is stale, task is done, or clear sensitive data') and mentions pairing with remember/recall. Lacks explicit 'when not to use' or named alternatives, but gives clear contextual guidance.

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

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

The description discloses the fetch-extract-emit workflow and mentions output placement ('ready to drop at site-root/llms.txt'), adding behavioral context beyond the annotations. The annotations already cover safety (read-only, idempotent), and the description enriches this without contradiction.

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

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

The description is concise—three sentences that front-load the purpose, then explain the process, and finally list use cases. Every sentence adds value without redundancy.

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

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

For a relatively simple tool with two parameters and no output schema, the description fully covers purpose, behavior, output format, and use cases. The annotations handle safety, so nothing critical is missing.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' already described in the schema. The tool description does not add additional meaning about the parameters beyond stating that links are extracted, so it does not exceed 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 uses a specific verb 'Generate' with a clear resource ('llms.txt file') and target ('any URL'), making the tool's function immediately obvious. It also distinguishes itself from sibling tools like ai_visibility_check by focusing on creating the file rather than analyzing AI visibility.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear guidance on when to use the tool. It does not mention alternatives or exclusions, but the context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive properties. The description adds useful behavioral context: the external service (Nominatim), a result limit of up to 5, and the specific return fields. This goes beyond the annotation baseline without contradicting it.

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, front-loaded with the core action, followed by constraints and return fields. Every word earns its place, with no fluff.

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

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

For a single-parameter read-only tool, the description covers purpose, data source, result limit, and return shape. Combined with the existing output schema and annotations, it leaves no significant gaps.

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

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

The schema fully documents the single query parameter with an identical description, so schema coverage is 100%. The description reinforces the input type but adds no new semantic meaning beyond what the schema already provides.

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

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

Clearly states the tool converts an address or place name to up to 5 matching coordinates, specifying the data source (OpenStreetMap Nominatim). This distinguishes it from reverse_geocode and other siblings.

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

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

The description clearly implies when to use it: when you have an address or place name and need coordinates. It doesn't explicitly name alternatives like reverse_geocode, but the context is unmistakable.

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 and non-destructive; the description adds the list of returned fields and input flexibility, but does not add deeper behavioral details like error handling 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?

Two sentences, front-loaded with the action, then examples, return values, and usage—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 simple one-parameter read-only lookup with an output schema, the description covers purpose, input, output, and usage context sufficiently.

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

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

Schema description is 100% complete for the single parameter, and the description's examples ('US', 'France') mirror the schema examples, so it adds no additional semantic value.

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

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

The description clearly states the tool retrieves country information by name or ISO code, listing specific return fields. This distinguishes it from sibling tools like geocode or get_timezone.

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 a clear usage context ('Use for regional context or facts') but does not explicitly mention when not to use it or alternative tools.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable context beyond these: it references the Sunrise-Sunset API as an external dependency and lists the specific fields returned (solar noon, civil twilight, day length). It does not contradict annotations and provides meaningful behavioral details.

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

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

The description is a single, well-structured sentence that front-loads the primary action, lists key outputs, and includes input parameters and defaults. Every phrase earns its place with no redundancy or filler.

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

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

For a simple read-only tool with a full output schema and comprehensive annotations, the description is complete. It covers inputs, optional parameters, defaults, the external API source, and the expected return fields. No critical information is missing for an agent to decide on and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the schema by clarifying that date is optional and defaults to today, but it does not add materially new information about parameter formats or constraints beyond what the schema already provides. The schema descriptions for latitude, longitude, and date are sufficient.

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

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

The description uses the specific verb 'Fetch' and clearly identifies the resource: sunrise/sunset data including solar noon, civil twilight, and day length. It also specifies the required inputs (latitude/longitude) and optional date, making it distinct from sibling tools like geocode or get_timezone.

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

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

The description clearly implies when to use this tool: when sunrise/sunset times are needed for a given location and optional date. It states the default behavior (defaults to today) and the API source, but does not explicitly mention alternatives or exclusions. Context is clear, though no 'when not to use' guidance is provided.

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, covering the safety profile. The description adds valuable context beyond these: it discloses dependency on an external service (TimeAPI.io) and a hard input constraint (requires coordinates, not city names), which helps the agent understand potential failure modes and appropriate usage.

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

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

The description is two sentences with no redundancy: the first states the purpose and outputs, the second clearly states the input requirement and exclusion. Every word serves a functional role, making it appropriately concise and front-loaded.

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

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

The tool is simple (2 params, read-only, with output schema) and the description fully covers its purpose, inputs, and constraints. The annotations and output schema handle safety and return structure, so the description does not need to elaborate further. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates that parameters are coordinates but adds little beyond the schema's minimal 'Latitude'/'Longitude' text. The schema examples (e.g., 40.7128, -74.006) provide typical format guidance, but the description itself does not significantly enhance parameter meaning beyond reinforcing the coordinate requirement.

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 ('Look up') and precisely identifies the resource (IANA timezone name, current local time, UTC offset) for a given latitude/longitude. It also distinguishes itself from siblings by explicitly stating it does not accept city names, which is a key differentiator from geocoding tools in the sibling list.

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 an explicit when-to-use ('for a given latitude and longitude') and when-not-to-use ('does not accept city names'). This exclusion clearly signals to the agent that if city names are available, another tool (e.g., geocode) should be used instead, even though no alternative is named.

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 behavioral context by listing the return fields (id, type, params, etc.) and specifying that it lists 'active subscriptions,' implying the default filter and the include_inactive parameter.

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

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

Two sentences, front-loaded with the action and output fields, then a concise usage hint. Every sentence earns its place with no redundancy.

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

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

For a simple read-only list operation with one optional parameter, the description fully covers purpose, output fields, and typical use cases. It also fits well among sibling tools like subscribe and unsubscribe, providing enough context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: the only parameter, include_inactive, is fully documented in the schema. The description reinforces the default behavior ('active subscriptions') but adds no new meaning beyond the schema.

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

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

The description uses a specific verb ('List') and resource ('subscriptions') with the scope 'the caller's active subscriptions.' It clearly distinguishes from sibling tools like subscribe, unsubscribe, and recent_alerts by indicating it lists existing subscriptions for review.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' It does not name alternative tools or exclusions, but the usage context is clear enough to guide tool selection.

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

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

Annotations provide no behavioral signal (all false), so the description carnes full burden. It discloses the write/send nature, the claim_token workflow for anonymous filing and later status checks, daily digest reading, rate limits (5 per identifier per day), and that it is free. This is rich, relevant behavioral context beyond the neutral annotations.

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

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

The description is a dense paragraph but every sentence earns its place: purpose, use cases, scope guardrail, content guidance, token mechanism, roadmap impact, rate limit, cost. It is front-loaded with the core purpose. Slightly long but not bloated; a structured list could improve scannability without adding 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?

Given no output schema, the description compensates by explaining return values (claim_token for anonymous filing) and the retrieval workflow. It covers scope, exclusions, message content guidance, rate limits, and cost. For a feedback tool with a nested context parameter, the description is complete and leaves no major operational gap for an agent.

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

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

Schema descriptions already cover all parameters 100%, so baseline is 3. The description adds workflow semantics beyond the schema: explains how claim_token is used round-trip (filing returns a token, later passed back to check status) and instructs to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which enriches the message/context parameter meaning.

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

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

Purpose is explicit and specific: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the verb (tell/send feedback), the resource (Pipeworx team), and the scope (Pipeworx tools). The description also distinguishes it from sibling tools by explicitly defining its boundary (only for Pipeworx connection tools) and contrasting with 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?

The description gives concrete when-to-use scenarios: bug (wrong/stale data), feature/data_gap, praise. It explicitly states when NOT to use it (other vendors' MCP servers) and directs the agent to file with that server instead. This provides strong guidance on alternatives and exclusions, exceeding baseline expectations.

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 meaningful context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window,' which go beyond the annotations to disclose aggregation source, privacy, and caching 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 four sentences, front-loaded with purpose, uses a numbered use-case list, and ends with a brief aggregation/caching note. Every sentence carries distinct information, with no filler or redundancy.

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

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

Given the tool's simplicity (1 optional parameter) and strong annotations, the description fully equips an agent: it explains what is returned, provides use cases, and covers operational details like caching and PII. No output schema exists, but the return description is sufficient for correct invocation.

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

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

The schema fully describes the single `window` parameter with an enum and explanation of shorter vs longer windows. The tool description repeats the options but adds no new semantic detail beyond what the schema already provides, so it lands at 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now,' and immediately details that it returns top tools, top packs, and total call volume over a window. This verb+resource framing distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description provides explicit use cases under 'Useful for:': discovering hot data sources, confirming a canonical tool, and checking use-case alignment. It does not name alternative tools or state when not to use, but the context is clear and actionable.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavioral context: threshold (3pp), similarity anchor (0.30 Jaccard), placeholder filters (>20% null signal), and the fill check caveat (realizable_edge_pp <= 0 means do not trade). This goes well 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 long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. It could be tightened, yet every sentence contributes meaningful details, 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?

No output schema, so the description must explain return values; it does (opportunities[], partition_check, fill_check). It covers edge cases (placeholders, low similarity, unexecutable edges), mode differences, and directs to a sibling for custom sizing. Extremely complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for event and topic, but the description adds significant extra meaning: event slug and topic examples, mode-specific behavior, URL acceptance, and how each parameter affects scanning. It elevates beyond the schema's bare definitions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges (edge detection) and polymarket_fill_risk (execution risk) by focusing on arbitrage detection methods.

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 mode selection: no args for trending_scan, `event` for specific market, `topic` for cross-event scanning. It also names an alternative tool for custom sizing ('polymarket_fill_risk') and explains when cross-event mode is beneficial.

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, idempotentHint, destructiveHint). It discloses the three model families, explains the caveats (e.g., 'your edge may already be in the price' via 24h-move warning), reveals caching behavior ('Cached 1h at the KV level'), and details what diagnostics are included (_diagnostics) to explain empty segments. This is rich behavioral context.

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

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

The description is long but well-structured and front-loaded with its main purpose. It uses clear segments (model families, knobs, response top-level) and every sentence adds information. It's not as concise as a two-liner, but the complexity of the tool justifies the length. Slightly dense but not wasteful.

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

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

There is no output schema, so the description takes the burden of explaining return values. It enumerates fields on every opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), describes the top-level response structure (by_segment, fed_candidates, _diagnostics), and explains why a segment might be empty. This is complete for an agent to understand and invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining parameter interactions, such as why min_kelly never filters partition arbs and how min_partition_leg_kelly applies to per-leg Kelly instead. It also contextualizes slippage_pp with real-world pricing assumptions, adding value beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan'), names the resource ('Polymarket markets'), and adds the unique angle ('Pipeworx data disagrees') that distinguishes 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 provides clear usage context ('Built for "what should I bet on today"'), explains when to use knobs (e.g., 'Set to 2 to require tight books'), and identifies the target user (agents discovering opportunities). It doesn't explicitly name alternatives or say 'use this instead of X', but it's clear enough for an agent to decide.

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

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

Beyond annotations (readOnly, idempotent), the description discloses critical behavioral details: edge_pp_net is signed by trade direction ('negative = SELL YES'), decay is computed on absolute value, snapshots are written on cache-miss ('gaps mean nobody scanned that day'), history is limited by a 60-day TTL, and decay comes from daily closes not intraday. These are essential for interpreting results and are not available in annotations.

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

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

The description is long but well-structured with clear sections (Args, RESPONSE, LIMITS). It is front-loaded with the core purpose and each section adds essential information. It is dense and not redundant, though it could be trimmed without losing value.

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

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

With no output schema, the description fully explains return values: tracked[], expired[], and snapshot_dates[], including their structure and meaning. It also covers limitations like TTL, snapshot gaps, and decay methodology, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds 'lookback' and 'snapshot family' context, but schema already says 'Lookback in days' and 'Which polymarket_edges window family to read snapshots for', so no significant additional meaning is provided.

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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers 'how long has this edge existed and is it shrinking?'. It differentiates from sibling polymarket_edges by focusing on historical persistence rather than just current edges, making the tool's role 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 implies when to use it: when you need to distinguish a fresh wide edge from an aged one. It contrasts 'a fresh wide edge and a 3-week-old wide edge are different trades', giving clear context. However, it does not explicitly name alternatives or state when not to use it, like 'for current edges use polymarket_edges'.

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 rich behavioral context beyond the readOnlyHint annotation: it explains how order-book depth is walked, what outputs to expect (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, capture_ratio, etc.), and warns about thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is long but efficiently structured, separating single-market and basket modes and enumerating outputs. Every sentence adds value, though the text could benefit from bullet points or headers. It is front-loaded with the core purpose, 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 carries full burden of explaining return values, and it does so comprehensively for both modes: listing all major output fields, edge cases (thin_legs, max_clean_notional_usd, forced_directional_risk), and practical usage scenarios. Given the tool's complexity, this is remarkably complete.

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

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

Despite 100% schema coverage, the description significantly enriches parameter meaning: it explains that 'side' behaves differently in single-market vs basket mode, and that 'size_usd' is interpreted as spend, target proceeds, or settlement notional depending on context. This goes well beyond the schema's basic field descriptions.

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

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

The description opens with a specific action ('Realizable-vs-theoretical edge check') and names the resource ('live CLOB order-book depth'), clearly distinguishing it from sibling tools. It explicitly references when to use this tool over polymarket_arbitrage and polymarket_edges, making the purpose unmistakable.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the failure mode (partial basket fills convert arbs to unhedged directional positions), giving clear when-to-use and why-to-use contexts.

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 read-only annotations, the description reveals critical behavioral details: compatibility_warning conditions (matched_pairs:0 vs skipped_cross_type), temporal_alignment affecting spread validity, and skipped_cross_type/subtype counters explaining dropped comparisons. It also discloses that real spreads are rarer than expected, adding significant transparency.

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

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

The description is long but well-structured into logical sections (introduction, modes, response, safety fields). Every sentence conveys meaningful information with no fluff, but its length is at the upper edge of appropriate for the tool's complexity. It is not as succinct as the two-sentence example but remains efficient and organized.

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 thoroughly explains the response structure (leg-by-leg prices, spread[], top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and nuances like temporal alignment. It covers all essential aspects for an AI agent to understand what to expect.

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

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

The schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds extra semantics by explaining the two modes (topic vs explicit), that explicit tickers override the topic-mapped sides, and by listing the valid topic values. This adds value beyond the schema's descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines what the tool does and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on other aspects of Polymarket.

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

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

The description clearly outlines two usage modes (topic shortcuts vs explicit tickers) and provides context on when each is appropriate. It also warns that 'pre-mapped ≠ tradeable' and that compatibility_warning indicates non-equivalent bet shapes. However, it doesn't explicitly mention alternative tools or direct when-not-to-use scenarios beyond the caution.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping behavior (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all. No contradiction; adds useful context beyond annotations.

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

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

Three sentences, each earning its place: purpose + list behavior, usage context with examples, and scoping + sibling relationships. No fluff, front-loaded with the main 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?

Tool is simple (1 optional param, no output schema). Description covers purpose, usage, scoping, and related tools. Nothing important is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% with a description for the 'key' parameter. Description reinforces the semantics ('omit to list all keys') and provides illustrative examples of what keys might represent, adding practical meaning beyond the schema.

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

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

Description uses specific verbs 'Retrieve' and 'list' with a clear resource (values saved via remember). It distinguishes from sibling tools by explicitly naming remember and forget, and provides concrete examples of use cases (target ticker, address, research notes).

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?

States clear when-to-use context: 'look up context the agent stored earlier... without re-deriving it from scratch.' Also pairs with remember and forget, indicating relationship. Missing explicit exclusions or alternatives, but the tool's role is well-defined.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing the return payload structure (source, citation_uri, raw event payload), the side effect of mark_read (flags events and ensures next call returns only newer ones), and explicit polling safety. It also mentions the persisted feed and alternative HTTP endpoint, adding rich behavioral context.

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

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

The description is well-structured and front-loaded with the main purpose. Each sentence adds necessary information: return payload details, filtering options, mark_read behavior, and polling/alternative HTTP access. There is no fluff or repetition, making it appropriately sized and efficiently organized.

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 five optional parameters and no output schema, the description is remarkably complete. It covers the return format, filtering semantics, state-changing behavior of mark_read, and even an alternative access method. An agent can understand how to use the tool correctly without additional 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?

With 100% schema coverage, the baseline is 3. The description adds value by providing a concrete example for type ('sec_8k'), clarifying the since parameter as an ISO timestamp, and explaining the consequence of mark_read (only newer events on next call). This practical context enhances the parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: pulling fired events from the subscription feed. It uses a specific verb ('Pull') and resource ('subscription feed'), and further specifies that it returns recent alerts with source, citation_uri, and raw payload, distinguishing it from sibling tools like list_subscriptions which manage subscriptions rather than retrieve events.

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 retrieve recent alerts, filter by type and/or since, mark events as read, and poll the feed. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state when not to use it, so it misses the 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, etc.), the description discloses multi-source fan-out, fallback behavior due to rate limits/5xx, the PatentsView API sunset causing soft-fail, and the exact return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). No annotation contradiction.

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

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

The description is dense but every sentence contributes: user intents, source fan-out, parameter semantics, return structure, and alternative tool. It is front-loaded with examples and structured logically, earning its length.

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

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

For a complex multi-source tool with no output schema, the description covers purpose, parameters, fallback behavior, return shape, and alternatives. It is fully self-contained and leaves no significant gaps for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by explaining the `since` parameter's ISO/relative shorthand with examples and recommending '30d'/'1m' for typical monitoring. This goes beyond schema descriptions, warranting a 4.

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

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

The description opens with concrete user intents ('What's new with X') and clearly defines the tool as a change feed for a company over a time window, fanning out to SEC, GDELT/GNews, and USPTO. It explicitly distinguishes itself from the sibling tool entity_profile, making its purpose unmistakable.

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

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

The description provides explicit usage examples ('latest on Y', 'updates on Acme') and direct guidance to use entity_profile instead for static profiles regardless of window. It also explains the fallback logic between GDELT and GNews, giving clear when-to-use context.

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

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

The annotations already indicate an idempotent, non-destructive write, and the description adds valuable context beyond that: storage scoped by identifier, authentication-based persistence vs. 24-hour anonymous retention, and the key-value pair model. This covers retention and scoping without contradicting annotations.

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

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

Three sentences, front-loaded with the primary action, and every sentence contributes: what it saves, when to use it, how storage works, and how it relates to siblings. No wasted words.

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

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

For a simple write tool with two required params and no output schema, the description fully covers purpose, usage, retention behavior, and relationships to recall/forget. The annotations handle idempotency and safety, and the description covers all else needed for correct invocation.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description reinforces the key-value pair model and adds context about 'any text' for values and identifier scoping, slightly going beyond the schema. It adds a bit of extra meaning without needing to compensate for gaps.

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

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

The description clearly states a specific verb ('Save data') and resource ('data the agent will need to reuse later') and distinguishes itself from siblings by mentioning 'across this conversation or across sessions' and pairing with recall/forget. It is immediately obvious what the tool does and how it differs from related 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?

Explicit guidance is provided: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives and companions: 'Pair with recall to retrieve later, forget to delete,' clearly telling when to use this tool vs. alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it cascades through multiple lookup endpoints, gracefully degrades when GLEIF/OpenFIGI is unavailable, explicitly labels unresolved identifiers, and explains ISIN-to-LEI mapping. These details are not captured by the readOnlyHint, idempotentHint, or openWorldHint annotations and are highly useful for an agent.

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

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

The description is longer than typical, but every sentence carries useful information—examples, supported types, source details, fallback behavior. It is front-loaded with common queries and clearly organized. It is not overly verbose for its complexity, earning a score above average.

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 multi-source complexity and absence of an output schema, the description thoroughly covers what the agent needs to know: supported entity types, input formats, return content (identifiers with source labels, unresolved list), internal cascading, and graceful degradation. It provides complete contextual guidance for an AI agent.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds extra semantics by providing concrete example values for 'value' (AAPL, 0000320193) and explaining the ISIN behavior for company lookups, enriching understanding beyond the schema.

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

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

The description explicitly states the tool resolves a user-spoken NAME to canonical/official identifiers, with specific verbs like 'resolve' and 'look up'. It provides concrete query examples (e.g., 'What's the ticker for…') and distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID', making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and inputs, making the context clear. However, it does not explicitly mention alternative sibling tools or when not to use this tool, though the directive 'Use FIRST' strongly implies precedence.

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

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

Annotations already declare the tool safe (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds that the output includes street address, city, country, and postal code, but this is likely already specified in the output schema. No additional behavioral traits (e.g., coordinate system, accuracy, rate limits) are disclosed, so the description adds marginal value beyond annotations.

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

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

Two concise sentences, front-loaded with the operation and result. No filler words or redundant information.

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

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

For a simple two-parameter read-only tool with comprehensive annotations and an output schema, the description is sufficient. It states the purpose, inputs, and output fields, and differentiates from the sibling geocode 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?

Both parameters have descriptions in the schema ('Latitude', 'Longitude'), covering 100% of parameters. The description's 'lat/lng pairs' adds no new detail about formats, ranges, or required coordinate systems. 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 uses a specific verb ('Convert') and names the resource ('coordinates to a physical address'), clearly distinguishing it from the sibling 'geocode' tool which does the opposite direction. This is a precise statement of the tool's function.

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

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

The final sentence explicitly states the intended use case ('Use to identify locations from lat/lng pairs'), providing clear context. It doesn't explicitly mention alternatives or when not to use, but the sibling list and the 'reverse' naming make the contrast implicit.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description doesn't need to restate those. It adds meaningful behavioral detail beyond annotations: it explains that the tool internally probes each entity using ai_visibility_check, ranks results by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotation-provided safety profile.

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

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

The description is three sentences long with a front-loaded purpose, followed by method, use case, and return value. Every sentence earns its place, with no filler or repetition of schema content. Excellent structure.

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 correctly explains the return value ('ranked list with score, confidence, signal density per entity'). It also conveys the tool's overall behavior and use case. It could have mentioned potential performance implications of probing multiple entities, but for a read-only comparison tool with strong schema coverage, this is nearly complete.

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

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

The input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds minimal extra parameter-level meaning: it restates that entities are 'your brand + N competitors' (already in schema) and mentions the ai_visibility_check integration, but does not clarify other parameters like models or context beyond what the schema provides. Thus baseline 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 clear action: 'Compare AI visibility across multiple entities side-by-side.' It specifies the exact scope (multiple entities), the method (probes each with ai_visibility_check), and the deliverable (ranked list). This differentiates it from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking, and from generic compare_entities by focusing on AI visibility.

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 frames the tool's use case: 'Useful for competitive AI-marketing audits' and provides a concrete example question. This gives clear context for when to use it. However, it does not explicitly state when NOT to use it or name alternative tools in the description, so it stops short of a 5.

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

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

The description discloses composite fan-out, partial failure behavior, timing ('bundlephobia's first measurement... can take 5-30s'), and the sources_failed field. These details go well beyond the readOnly/idempotent annotations, which already establish safety.

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

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

The description is long but every sentence carries crucial information: purpose, use cases, return shape, ecosystem boundary, and failure behavior. It is front-loaded with the core purpose and avoids redundancy.

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

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

With no output schema, the description fully enumerates returned fields (is_latest, license, published_at, etc.) and explains degradation. It also covers the only major limitation (npm-only in v1). This is complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds little beyond the schema: it reinforces that package is an npm package but does not elaborate on version semantics already covered. No further parameter-level information is needed.

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

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

The description clearly states a specific composite action: a 'should I add this npm package to my project' check combining deps.dev and bundlephobia. It identifies exact resources and clearly distinguishes itself from a direct deps.dev version check for other ecosystems.

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 whenever an agent asks "is X safe / popular / small"' and for npm only. It also states when not to use it: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', naming the alternative.

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

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

Beyond the annotations, the description discloses specific behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. This adds significant context beyond the read-only/idempotent 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 concise yet information-dense, front-loaded with the primary purpose, followed by usage guidance and implementation details. Every sentence contributes value without unnecessary verbosity.

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

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

Given no output schema, the description adequately explains return values (passages with offsets and scores) and edge-case behavior (truncation). It also integrates with the sibling tool ask_pipeworx_grounded, providing complete context for an agent to use the tool effectively.

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

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

The input schema already provides complete descriptions for all three parameters (100% coverage). The description adds some context, such as query examples and the source of the text, but it largely repeats schema information, so it does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a previously fetched record, with a specific verb and resource. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by emphasizing it works on a passed text and returns passages with offsets.

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

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

Explicitly states when to use: when a record is too big to fit in the prompt, and mentions pairing with ask_pipeworx_grounded for a recommended workflow. It also implies a comparison to grounding over whole documents, giving clear context.

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

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

Annotations cover readOnly/idempotent/destructive hints, but the description adds substantial operational behavior: OAuth requirement, persistent feed always on, optional email/SMS/webhook delivery, SMS daily cap, webhook auto-disable after 10 failures, and one-time signing secret. This goes far beyond annotation data.

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

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

The description is long but dense, covering multiple subscription types and delivery channels in a structured way. It front-loads purpose and returns value, though it could be slightly tighter with bullet formatting for the type variants.

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 nested parameters and no output schema, the description covers the return value (subscription id), authentication prerequisite, channel behavior, SMS cap, webhook failure handling, and how to consume the always-on feed. This is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100% and already details all parameters. The top-level description adds a few meaningful semantics not in the schema, such as item code meaning ('5.02' = officer change) and polymarket_edge's cross-venue mispricing context, but largely duplicates schema content.

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 action: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe by emphasizing creation of a new subscription.

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

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

It provides clear usage context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, and details supported subscription types. It doesn't explicitly name alternatives like list_subscriptions or unsubscribe, but it does mention pulling alerts via recent_alerts, which helps situate the tool's role.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds context by stating that it returns category-bucketed example questions with exact tool+argument shapes, and that the catalog is live. It also documents behavior with no arguments versus with a topic, 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 longer than two sentences but every sentence contributes: the leading example queries help match intents, the body explains return value and structure, and the closing gives usage instructions. It is well-organized and not redundant.

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 optional parameter and no output schema, the description is complete: it explains what it returns, how it composes examples (with exact tool + argument shape), the source (live catalog), and how to call it. No significant behavioral gaps remain.

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

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

The schema already covers the optional 'topic' parameter with a description listing allowed values. The description adds value with concrete examples ('finance', 'pharma', 'betting') and clarifies that omitting it returns a cross-category spread. This is useful guidance 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 identifies suggest_questions as the onboarding entry point for an agent that just connected, returning category-bucketed example questions each with the exact tool and argument shape. It distinguishes itself from siblings by explicitly naming meta-tools (ask_pipeworx, entity_profile, compare_entities) and positioning itself as the first step to learn 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?

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to tailor by topic versus full spread. It doesn't explicitly state when not to use it, but the 'FIRST' instruction and mention of alternative meta-tools imply a clear use case.

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

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

Beyond annotations, the description adds valuable context: ownership enforcement, soft-deactivation (not deletion), and preservation of historical events via recent_alerts. These details clarify side effects and data lifecycle, exceeding what annotations alone 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 two sentences: the first states the core action, and the second adds key behavioral details. It is concise, front-loaded, 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?

For a single-parameter tool with clear annotations, the description covers purpose, constraints, and the soft-delete behavior, even referencing recent_alerts for downstream availability. No output schema is needed, and all essential information is present.

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

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

The input schema already fully documents the 'id' parameter with its description, and the tool description adds no additional parameter semantics. With 100% schema coverage, 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 states 'Cancel a subscription by id' with a specific verb (cancel) and resource (subscription), making the operation unmistakable. It distinguishes itself from siblings like subscribe and list_subscriptions by clearly focusing on cancellation.

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

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

The description implies usage for canceling subscriptions but does not explicitly contrast with alternatives or state when not to use. It mentions ownership enforcement as a constraint but lacks explicit guidance on when to choose this tool over subscribe or list_subscriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond those: the critical distinction that 'could_not_verify' is a failure state not evidence, the 'unsupported' meaning, the two routing paths (SEC EDGAR structured vs grounded pipeline), and the presence of verification_error{stage,detail}. This enriches the agent's understanding without contradicting annotations.

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

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

The description is relatively long but every sentence earns its place: trigger examples, routing logic, verdict enum, caller caveat, and pipeline replacement. It is front-loaded with the most critical usage signal (trigger phrases) and structured logically. No fluff or repetition.

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

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

With no output schema, the description carries full responsibility for explaining return values. It lists the verdict enum, the output components (actual value with citation, reasoning), and distinguishes between 'could_not_verify' and 'unsupported'. It also covers the two major claim categories (financial vs other) and the overall pipeline, making the description self-contained for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides for 'claim' and 'tolerance_pct'. It mentions 'tolerance' only in the context of verdict grading, not as a parameter explanation. Thus, no additional 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?

The description opens with concrete trigger phrases ('Is it true that…', 'fact check') and explicitly states 'natural-language claim verification against authoritative sources.' The verb (verify/validate), resource (claims against authoritative sources), and scope (factual correctness) are clear. It distinguishes itself from sibling search/research tools by focusing on claim verification with a verdict output.

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

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

The description provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes it replaces 4–6 sequential calls, positioning it as a single-call alternative. However, it does not name sibling tools to avoid or state explicit when-not-to-use conditions, preventing a 5.

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