Pypi Stats

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds significant behavioral details: default model (Workers AI Llama-3.3-70b), BYO API key requirement for Anthropic, and the return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

The description is concise (4-5 sentences) and well-structured: action, model options, return format, use cases. Every sentence adds necessary information without redundancy.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description fully covers input expectations, behavior, and output structure. It provides enough detail for an agent to use the tool correctly, especially with the annotations supporting the safety profile.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the default model for the 'models' parameter, the role of '_apiKey', and how 'context' disambiguates entities. This goes beyond the schema's basic descriptions.

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

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

The description uses specific verbs ('Probe', 'score visibility') and clearly identifies the resource (LLMs' knowledge of a business/brand/product/topic) with a measurable output (0-100 score). It distinguishes itself from siblings by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description explains when to use this tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to configure it (default model, conditional Anthropic probing). It does not explicitly state when not to use it or compare to siblings, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, lowering the bar. The description adds useful behavioral context: it fills arguments, returns structured answers with stable pipeworx:// citations, and is described as 'one fast call'. It does not disclose error handling or latency, but these are less critical given the read-only, idempotent 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 front-loads the key directive and use cases, then provides examples and escalation guidance. It is somewhat lengthy and slightly redundant in reiterating use cases, but every section serves a purpose for an agent deciding when and how to use this tool.

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

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

For a tool with no output schema, the description adequately explains behavior, typical inputs, citation output, and alternatives. It covers the default entry point role, supported domains, and escalation path, making it complete enough for an agent to select and invoke correctly, though details on edge cases are absent.

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

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

Schema has 100% coverage for all 6 parameters, all aliases for 'question', with a clear description of natural-language input. The description adds example queries but no additional parameter syntax or semantics beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

Description clearly states it routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself by naming 'ask_pipeworx_grounded' and 'deep_research' as alternatives and identifying itself as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists many specific use cases (SEC filings, FDA data, FRED, patents, etc.) with trigger phrases like 'what is', 'look up', 'find'. It provides clear escalation guidance: 'use ask_pipeworx_grounded; ... use deep_research'.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by disclosing that the tool may behave differently when a candidate routing improvement is under test, and currently matches ask_pipeworx exactly. It also notes that results are compared against the stable router to decide merges, providing important behavioral context about the experimental 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 yet densely informative, with each sentence contributing unique value: what the tool is, current state, usage guidance, and confirmation of full functionality. It front-loads the key identity ('Beta version of ask_pipeworx') 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?

The description is complete for a query tool with strong annotations. It covers the tool's relationship to ask_pipeworx, the absence of fallback, the identical response shape, and the current inactive state of candidates. Since there is no output schema, the mention of 'same response shape' adequately addresses return expectations.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question' and a clear description. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same tools and response shape, and explicitly differentiates it from the stable version by noting the experimental routing improvements. It distinguishes itself from sibling tools like ask_pipeworx and ask_pipeworx_grounded by focusing on being the 'experimental edge.'

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the alternative (ask_pipeworx) and explains that this version is a full working router, not a fallback, eliminating ambiguity about when to invoke it.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses critical behavioral traits: it uses only the tool result content, returns structured evidence and confidence, and produces explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also mentions the extra LLM call cost, which annotations do not cover.

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

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

The description is dense and every sentence contributes: it defines the mode, outlines the routing/process, provides return and refusal formats, gives use cases, and compares cost. It is somewhat long but structurally efficient for the tool's complexity, earning a high but not 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?

With no output schema, the description fully specifies the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerates all refusal reasons. It also refers to ask_pipeworx for shared routing context, 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?

All six parameters are aliases for a single natural-language question, and the input schema already documents this thoroughly with 100% coverage. The description does not add additional parameter semantics, but none are needed given the schema's completeness. Baseline of 3 is appropriate.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads, extracting answers only from tool results. It explicitly differentiates itself from ask_pipeworx by adding grounded extraction and refusal behavior for cases where the data doesn't directly answer.

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: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts. It also names the alternative (ask_pipeworx) and states to prefer it for casual lookups, including the cost trade-off of one extra LLM call.

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

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

The description extensively details behavioral traits beyond annotations: response shapes, resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence matches, closed markets, wide spreads), and cancellation rules. This rich context adds significant value beyond the readOnly and 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 verbose but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). It front-loads the purpose and input format. While every sentence adds value, the length could be optimized for faster agent 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?

With no output schema, the description fully explains return shapes (result.market, result.analysis, result.evidence), match confidence levels, parent event extraction, news fallback fields, and error/edge cases (closed markets, wide spreads, cancellation rules). It leaves no ambiguity about what the tool returns.

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

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

Schema coverage is 100%, but the description adds substantial meaning: clarifies the market parameter (slug, URL, question text), explains depth default behavior, and details include_raw's effect on response size. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and distinguishes itself from siblings like polymarket_edges by focusing on comprehensive research for a single bet.

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

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

Explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it provides clear guidance on when to use, it does not explicitly state when not to use or mention 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details what data is fetched for each type (SEC filings for companies, FAERS for drugs), how fiscal years are handled, sorting by primary metric, and return of citation URIs. This provides excellent behavioral insight.

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 packed with useful information in a single paragraph, but it is not overly long. It front-loads the purpose and usage triggers. A slightly more structured format (e.g., bullet points) could improve readability, but it's already efficient.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains the inputs, data sources, and behavior (fiscal year handling, sorting). It doesn't detail the exact output structure, but it provides enough for an agent to decide correctness.

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 description coverage, the description still adds value by giving concrete examples (e.g., 'AAPL','MSFT' for companies, 'ozempic','mounjaro' for drugs) and explaining what data each type retrieves. This goes beyond the schema's basic type and constraints.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides specific natural language triggers and distinguishes from sequential lookups, making the purpose immediately clear.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear usage guidance. It also explains when to use company vs drug type. However, it lacks explicit exclusions or when not to use it, but the context is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context beyond annotations: it explains that it never invents findings, includes explicit gaps[], contradicts[] for standard/thorough, describes response fields (verbatim evidence, confidence, source, fetched_at, citation_uri), cites hop field, describes latency expectations (15-60s, up to 90s), and explains excerpting behavior. It even notes citations are only present when fetchable, and covers account/plan requirements (free sign-in, paid for thorough). This fully complements annotations with no contradictions.

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

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

The description is dense and front-loaded with the most critical info (account requirement, not open-web, best use case). It packs a large amount of valuable detail into a single paragraph. However, it runs long and could be structured with clearer separations (e.g., bullet points for depth tiers or caveats). Slightly wasteful to repeat 'contradictions[]' twice, but every sentence earns its place for an unusual tool.

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

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

Given the tool's complexity (5,529 tools, multi-facet research, varying depth tiers, large records) and the absence of an output schema, the description covers all major aspects: input semantics, output shape, error/empty behavior (gaps[]), latency, auth requirements, and alternatives. It leaves little ambiguity about what the tool returns and how to interpret it, making it complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, with detailed descriptions for both parameters (depth enum with per-tier behavior, question with note that broad questions are fine). The description adds the distinction that quick=3 facets, standard=5, thorough=8 and explains what each does beyond the schema's wording. Since the schema already covers the parameters thoroughly, the description's marginal addition is moderate, so a 3 is appropriate per 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 opens with a strong verb+resource statement ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources') and explicitly distinguishes itself from open-web search and single-lookup tools like ask_pipeworx. It clearly states what it does (decomposes questions into facets, parallel routing to 5,529 tools, returns evidence packet) and contrasts with siblings in the same context.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and provides counter-examples: for single lookups use ask_pipeworx, and for breaking/colloquial current news prefer ask_pipeworx because deep_research returns gaps. It also explains depth tiers with behavioral consequences, giving clear selection criteria.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds that results include 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed'. No contradiction.

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

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

Two sentences, front-loaded with main purpose. Second sentence is somewhat long but packs useful information. Not overly verbose.

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

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

Given 6 parameters (1 required) and no output schema, the description explains tool purpose, usage, return format, and examples. Adequate for agent decision-making.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add significant meaning beyond schema; it just provides usage examples. No extra parameter details.

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

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

The description starts with 'Find tools by describing the data or task', clearly stating the tool's purpose as a discovery mechanism. It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings, none of which are discovery tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available'. No explicit when-not-to-use but implied 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?

Adds behavioral context beyond annotations: describes parallel fan-out across multiple sources, notes patent API sunset and soft-fail behavior, and details fallback chains (GDELT→GNews). Annotations already indicate read-only, open-world, idempotent, non-destructive; no contradiction.

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

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

Concise for the amount of information: front-loaded with example queries, every sentence adds value, no fluff. Structured logically from usage to details.

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

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

Given complexity (multiple sources, fallbacks) and no output schema, the description is very complete: explains exactly what is returned (cik, company_name, recent_filings with URIs, fundamentals sorted, patent status, news fallback, LEI). No 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?

Schema coverage is 100% but description adds meaning: explains type is only 'company' for now, value can be ticker or zero-padded CIK (with example), and explicitly states names not supported. Provides more context than schema alone.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call. It lists specific data sources and outputs, and distinguishes from sibling tools like resolve_entity and chaining single-pack lookups.

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

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

Explicit when to use: for holistic company profiles, with example queries. Also when not to use: if only a name is available, advises using resolve_entity first. States 'ALWAYS PREFER over chaining single-pack 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description merely repeats 'Delete' and adds no behavioral nuance beyond what annotations provide, so no additional value.

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: first defines action, second provides usage guidance. No fluff, front-loaded with essential info.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and sibling context. No gaps 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 covers 100% of parameters, describing 'key' as 'Memory key to delete'. The description adds no extra parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' – a specific verb and resource, distinguishing it from siblings 'remember' and 'recall' which are mentioned as pairings.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with remember/recall. Lacks explicit when-not scenarios, but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds detail: fetches page, extracts title/description/links, emits markdown. Aligns perfectly with annotations.

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

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

Three sentences: purpose, process, use cases. No unnecessary words, front-loaded with key information.

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

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

No output schema, but description explains output format. All necessary context provided for a simple tool with clear annotations.

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

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

Schema has full coverage (2 params described). Description adds usage context like 'site to summarize' and default/max for max_links, improving clarity beyond schema descriptions.

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

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

The description clearly states it generates a standard llms.txt file for any URL, specifying the exact output and process. It distinguishes itself from siblings like ai_visibility_check by focusing on file generation.

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

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

Provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor). Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds that it returns specific fields, which is consistent but adds little beyond annotations. No contradiction.

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

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

Two sentences, no fluff. First sentence states purpose and return fields; second gives usage guidance. Front-loaded and efficient.

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

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

No output schema, but description compensates by listing return fields (id, type, params, created_at, last_fired_at, fire_count). Tool is simple with one optional parameter; description is complete enough.

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

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

Schema coverage is 100% with the parameter include_inactive already described. Description does not add additional meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions.' It specifies the verb (list), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly indicates when to use and implies alternatives (subscribe/unsubscribe).

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds value by specifying the data source (pypistats.org), return type (timeseries), and optional filter behavior. It does not contradict annotations and provides useful context beyond them.

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

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

The description is a single, well-structured sentence. It is front-loaded with the action and resource, and every part adds value. No unnecessary words.

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

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

Given the simplicity of the tool, the description fully covers its purpose, source, optional filter, and return type. Output schema exists and annotations provide safety guarantees. No 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?

With 0% schema description coverage, the description compensates by explaining the 'mirrors' parameter explicitly (exclude mirror traffic). The 'package' parameter is implied by context but not formally described. This adds meaningful semantics for one of two parameters.

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

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

The description clearly states the verb 'Fetch', the resource 'daily PyPI download timeseries for a package', source 'pypistats.org', and optional filter. It is specific and distinguishes itself from all sibling tools, none of which deal with PyPI stats.

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

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

The description implicitly indicates usage by stating the source and optional filter. However, it does not explicitly mention when to use or when not to use, nor does it provide alternative tools. For a unique tool, this is acceptable but could be clearer.

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?

As annotations are all false, the description fully discloses the tool's behavioral profile: it is rate-limited to 5 per identifier per day, free, does not count against quota, and returning a claim_token is required for follow-up checks. It also explains that feedback directly affects roadmap, adding rich context beyond the schema.

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

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

The description is long but every sentence adds unique value: it front-loads the primary purpose, then guides usage, exclusions, token mechanics, and policy in a logical sequence. No redundancy or fluff; 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?

Despite having no output schema, the description explains the return value (claim_token) and its lifecycle. It covers prerequisites, rate limits, and even what happens after submission (daily digests, roadmap impact). The nested context object is clarified by the schema, and the description fills in all operational 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?

Schema coverage is 100%, so baseline is 3, but the description enhances the claim_token parameter by specifying the exact usage pattern ('pass the pwfb_… token that filing returned, with no other arguments') and elaborates on message expectations. This adds concrete operational detail not present in the schema.

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

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

The description opens with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature, data_gap, praise) and explicitly distinguishes itself from other MCP servers' tools. This fully differentiates the tool from its siblings.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states when NOT to use it (feedback for other MCP servers) and directs the user to the correct alternative, making exclusion criteria crystal clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This adds meaningful context for agent 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 (3 sentences) with the main purpose front-loaded. Every sentence delivers useful information without redundancy or 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 simple tool with one optional parameter and no output schema, the description adequately covers what is returned (top tools, packs, call volume) and the caching behavior. Minor gap: does not specify the exact return structure, but overall sufficient.

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

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

The input schema fully describes the window parameter with enum values and descriptions. The tool description reiterates the window options but adds no new semantic information beyond the schema, so minimal added 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 it returns top tools, packs, and call volume, with a specific verb ('returns') and resource ('what other AI agents are calling'). It distinguishes itself from siblings by focusing on trending data derived from actual usage.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tool, aligning with agent needs), providing clear context for when to use. However, it lacks explicit 'when not to use' or alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds critical behavioral context: computation of arbitrage, fill check against live CLOB depth, semantic anchor Jaccard similarity, partition filter, and conditions for valid trades. 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 and informative, but moderately long. Every sentence adds value; however, it could be slightly more structured (e.g., bullet points) for easier scanning. Still, far from verbose.

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

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

Given the tool's complexity (multiple modes, output with opportunities and fill checks, no output schema), the description covers all key aspects: output structure, edge cases (low similarity, placeholders), fill check logic, and references to related tools. Very thorough.

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

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

Input schema covers both parameters with descriptions. The description adds rich semantics: event slug examples (including URL acceptance), topic examples, and explains how the tool processes each parameter (walks child markets, searches related events).

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between no-arg trending scan, event mode, and topic mode, and uses specific verbs and resource references.

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 on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for... or `topic` for...' Also provides recommendations and disclaimers about when not to trade, and references the sibling tool polymarket_fill_risk for custom sizing.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint): it details caching (1h KV-level), model families, edge calculation, slippage, and tradeable-edge filters. 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 lengthy and dense, containing many details. While it is well-organized with segment groupings and crucial information, its verbosity reduces readability. It earns its length by covering important details but could be more concise.

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

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

Given the tool's complexity (multiple models, parameters, response structure) and lack of output schema, the description is thorough: it explains the response top-level (by_segment), diagnostics, and caching behavior. It leaves no critical gaps for an agent to understand the tool's behavior.

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

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

All 9 parameters are fully described in the input schema (100% coverage), and the tool description adds extra context on how they interact (e.g., min_partition_leg_kelly applies per-leg, not parent-level; tradeable-edge knobs drop opportunities). This significantly enriches 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 clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case: 'what should I bet on today'. It is a specific verb+resource combination, but does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description implies the tool is for discovering betting opportunities and notes that Fed bets are excluded from ranking, but it does not provide explicit when-to-use/when-not-to-use guidance or mention alternatives. The context is clear but lacks exclusions or comparisons to siblings.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, which the description does not contradict. The description adds behavioral context: explains response structure, trend/decay computation, snapshot timing, and history bounds. This goes beyond annotations.

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

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

The description is verbose but well-structured: purpose statement, argument details, response schema, and limitations. Each sentence adds value, but the length could be reduced for faster parsing. Front-loading with the key question helps.

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

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

No output schema exists, so the description fully explains the return format (tracked, expired, snapshot_dates) and meanings of fields. Parameters are fully described with defaults and constraints. Limitations are clearly stated, making the tool usable without external docs.

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%, providing baseline. The tool description adds value by explaining defaults (14 days, 1wk), constraints (max 30 days), and the meaning of 'window' as snapshot family with examples. This enriches parameter understanding.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily polymarket_edges snapshots, distinguishing it from the sibling polymarket_edges tool which likely provides raw edge data. The verb 'Answers' and the specific question make the purpose highly specific.

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 context by contrasting fresh vs. old edges, indicating when to use this tool to assess edge quality and decay. It also provides constraints (TTL, snapshot gaps) that guide appropriate use. However, it could explicitly state when to prefer this over sibling tools.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description reveals key behavioral traits: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and warns about forced directional risk from thin legs. This adds critical context not captured by annotations alone.

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

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

The description is front-loaded with the core purpose and then details modes and returns. While comprehensive, it could be slightly more concise by separating mode blocks more clearly. Every sentence adds value, making it effective but not maximally concise.

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

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

Given the complexity (two modes, detailed return fields, risk warnings), the description is thorough. It covers all return values for both modes, explains edge cases (cannot_fill), and provides actionable guidance. With no output schema, the description fully compensates by listing all fields.

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 value by explaining context (e.g., automatic side selection in basket mode, size_usd interpretation differences for buys vs sells and single vs basket, and clamp range). It clarifies parameter relationships better than the schema alone.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth, distinguishing between single-market and basket modes. It specifies the exact resource (Polymarket CLOB) and the action (risk assessment), differentiating 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?

Explicitly states when to use this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains why (theoretical overround not capturable on thin books) and warns against misuse (partial basket fills leading to unhedged positions), providing clear context for the AI agent.

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 idempotent. The description adds rich behavioral context: compatibility_warning conditions, temporal alignment constraints, skipped cross types, and the fact that most pre-mapped topics are non-tradeable. No contradictions with annotations.

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

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

Well-structured with clear sections (purpose, modes, response, safety fields), but slightly verbose. Every sentence adds value, but could be more concise without losing 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?

Given tool complexity (cross-venue, multiple modes, safety fields, temporal alignment), the description covers all aspects an agent needs, including pitfalls. No output schema, but response fields are thoroughly described.

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

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

Schema coverage is 100%; description adds meaning by explaining modes, providing example values, and clarifying override behavior. The description significantly enhances understanding beyond the schema alone.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same event. Distinguishes two modes (topic shortcuts and explicit pairings) and explains response content. No ambiguity with 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?

Explicitly describes when to use each mode, provides example topic values, and warns that most pre-mapped topics return compatibility_warning and are not automatically tradeable. This sets clear expectations and helps the agent decide when to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that data is sourced from pypistats.org and returns per-version counts, providing 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?

The description is a single sentence that efficiently communicates the tool's purpose and output. No unnecessary words; information is front-loaded.

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

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

Given the low complexity (one parameter, output schema exists), the description is complete. It explains what the tool does and what it returns. No missing information needed 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 0%, meaning the schema provides no description for the 'package' parameter. The description only implies it is the package name through the example. With a single required parameter, the meaning is inferred, but the description does not explicitly state format or constraints.

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 action ('Fetch PyPI download breakdown'), the resource ('package by Python major version'), and the data source ('pypistats.org'). It also mentions the return type ('per-version download counts'). This clearly distinguishes from sibling tool 'python_minor' which would handle minor versions.

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 major version breakdown, but does not explicitly state when to use this tool over alternatives like 'python_minor'. No when-not-to-use or exclusion criteria are 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, destructiveHint false. Description adds data source (pypistats.org) and return format (per-version counts), but no additional behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with verb and resource, zero unnecessary words. Efficient 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?

Simple tool with one parameter, annotations cover safety, and output schema exists. Description adequately specifies purpose and return format, lacking only minor detail on output structure.

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

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

Only one parameter 'package' with 0% schema description coverage. Description merely says 'Fetch PyPI download breakdown for a package', adding minimal meaning beyond the schema's example 'scipy'.

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 specifies verb 'Fetch', resource 'PyPI download breakdown by Python minor version', and gives examples (3.10, 3.11). Clearly distinguishes from sibling 'python_major'.

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?

No explicit when-to-use or when-not-to-use guidance. Context of sibling 'python_major' implies niche, but description lacks direct usage directives.

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

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

Annotations already indicate readOnly/idempotent/destructive behavior. Description adds scoping detail and pairing with remember/forget, which is 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 concise sentences, front-loaded with primary action. No redundant information; every sentence adds value.

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

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

Given simple tool with one optional param and no output schema, description covers retrieval, listing, scoping, and related tools completely.

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

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

Schema coverage is 100% and description restates the parameter behavior (omit to list). No new syntactic details beyond schema, but clarification of omission is helpful.

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

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

The description clearly states the tool retrieves a saved value (via remember) or lists all keys when omitted. It distinguishes from siblings like remember and forget.

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

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

Explains when to use (to look up context without re-deriving) and mentions scoping. Does not explicitly state when not to use, but provides clear context for usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it queries pypistats.org and returns a single aggregate count, providing useful external 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?

Single sentence of 22 words, front-loaded with verb and resource. 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?

With an output schema present, description need not detail return structure. It states returns a single aggregate count, which suffices. No mention of errors or limits, but acceptable for this low-complexity 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 has 50% description coverage (period gets a description, package does not). Description adds meaning for 'package' by stating it fetches count for a package, and clarifies period values as day, week, month. This compensates for schema 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?

Description specifies verb 'fetch', resource 'total PyPI download count for a package', and scope 'over a recent period (day, week, or month)'. Clearly distinguishes from siblings like 'overall' which likely covers all-time data.

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

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

Implies usage for recent period data but does not explicitly state when to use this vs alternatives, nor does it provide exclusions or prerequisites.

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

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

The description adds behavioral context beyond annotations: it explains that events are from a persisted feed, each carries source/citation_uri/payload, and that mark_read flags events so next call only shows newer ones. This supplements the readOnly and idempotent annotations. No contradictions.

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

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

The description is five sentences, each earning its place: purpose, return contents, filtering, mark_read behavior, and polling advice. It is front-loaded with the main action and contains no fluff or repetition.

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

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

For a 5-parameter tool with no output schema, the description fully covers what is returned (source, citation_uri, raw payload), parameter usage, and behavioral aspects (feed persistence, polling). It also mentions an alternative endpoint, providing complete context 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 coverage is 100%, but the description adds meaning beyond the schema by explaining how to use parameters: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp). Set mark_read:true to flag returned events read.' It also implies limit usage by mentioning default 50. This goes beyond bare 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 uses a specific verb+resource combination: 'Pull fired events from your subscription feed.' It clearly states what the tool returns and its purpose. While it doesn't explicitly distinguish from siblings, the unique focus on subscription feed alerts with filtering and mark_read makes the purpose clear 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?

The description provides usage context: filtering by type and since, setting mark_read for read tracking, and mentioning that polls work fine. It also notes an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when to use this tool versus sibling tools like list_subscriptions or recent.

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

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

Annotations already indicate safe, idempotent read. Description adds details on parallel fan-out to multiple sources, fallback behavior, acceptance of date formats, and output structure including citation URIs.

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

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

Single paragraph is dense but clear, front-loaded with examples. Could be improved with bullet points for sources, but overall efficient and readable.

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

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

No output schema, but description explains return shape: changes grouped by source, total count, and citation URIs. Covers error/fallback for GDELT and USPTO. Complete for a tool with 3 simple parameters.

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

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

Schema description coverage is 100%. Description adds examples for each parameter ('AAPL', '0000320193', '30d', '1m'), explains the 'since' format options, and clarifies that 'type' only supports 'company'.

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?

Explicitly states it returns a change feed for a company over a time window, with example queries. Distinguishes from sibling 'entity_profile' by noting the different use case.

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 for time-windowed changes, and use 'entity_profile' for static profiles. Also suggests typical monitoring interval '30d' or '1m'.

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

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

Adds value beyond annotations: explains key-value storage, identifier scoping, and persistence durations (authenticated vs anonymous). No contradiction with idempotentHint=true.

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?

One efficient paragraph, front-loaded with purpose, no wasted words. Every sentence adds essential information.

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

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

Fully adequate for a simple tool with two parameters and no output schema. Covers purpose, usage, behavior, and lifecycle.

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

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

Schema coverage is 100% but description adds context with example keys and clarifies that value can be any text, going beyond the schema descriptions.

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

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

The description clearly states the purpose: 'Save data the agent will need to reuse later', with specific examples (resolved ticker, target address) and contrasts with sibling tools (recall, forget).

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

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

Explicitly guides when to use: 'when you discover something worth carrying forward', mentions pairing with recall and forget, and provides context on scoping and persistence.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits such as graceful degradation ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return') and the explicit handling of unresolved identifiers under `unresolved`. This adds significant context 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, opening with concrete example queries, then stating the primary purpose, and then detailing supported types. Each paragraph adds necessary information. It is slightly verbose, but the complexity of the tool justifies the length.

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

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

The tool is complex with two distinct entity types and no output schema, yet the description covers input formats, output identifiers, source labeling, unresolved-identifier behavior, and degradation handling. It is sufficiently complete for an agent to understand what the tool returns and how it behaves under various conditions.

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

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

While the schema descriptions are already complete, the tool description adds substantial semantic detail, explaining accepted input formats for each type ('ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name' for drug) and outlining the specific identifiers returned for each type (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand). This far exceeds the basic 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 function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes example queries and distinguishes itself from sibling tools by focusing specifically on name-to-ID mapping, which is a unique role among the listed tools.

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

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

The description gives explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. While it does not explicitly name alternative tools or provide exclusion criteria, the context and precedence are clear.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate safety. The description adds that the tool probes entities via 'ai_visibility_check', ranks by score, and returns score, confidence, and signal density. No contradiction with annotations. This goes beyond the structured 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 three sentences with no fluff. The main action is front-loaded: 'Compare AI visibility across multiple entities side-by-side.' Every sentence adds distinct value (what it does, how it works, use case, output).

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 rich annotations and 100% schema coverage, the description is complete. It explains the internal probe mechanism, the output structure, and provides a practical example. No output schema, but the description lists returned fields (score, confidence, signal density).

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 value by explaining that the first entity in 'entities' is treated as the subject and that the array should contain brands/businesses. This contextualizes the parameters beyond the schema descriptions.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. It specifies the outcome: ranked list with scores. It distinguishes from sibling 'ai_visibility_check' by aggregating comparisons and from 'compare_entities' by its focus on AI visibility. The concrete use case about Claude recognition solidifies purpose.

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

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

The description explicitly advises using this tool for competitive AI-marketing audits, comparing multiple entities. It implies that for single-entity checks, one should use 'ai_visibility_check' instead. However, it does not directly exclude alternatives or differentiate from sibling 'compare_entities', which could cause ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond this: partial failures (bundlephobia timeout), sources_failed list, and the composite nature (fans out across services). No contradictions with annotations.

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

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

The description is fairly verbose but well-structured: it front-loads the core purpose in the first sentence, then elaborates on details. Every sentence adds value, though some minor trimming could improve conciseness without losing 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 composite tool with no output schema, the description fully explains the return content (summary block fields, per-advisory details, links, alternative versions). It also covers failure modes, ecosystem scope, and the multi-service fan-out, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so both parameters are described in the schema. The description adds minor context (scoped packages accepted, default version is latest), but the schema already provides sufficient semantics for an agent to understand the parameters.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, dependencies, ESM/tree-shake. It distinguishes from sibling tools by specifying the NPM ecosystem scope and directing other ecosystems to a different tool.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes what is not covered (PyPI, Maven, etc.) and offers an alternative for those ecosystems, helping the agent decide when not to use this tool.

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

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

Annotations already indicate safe, idempotent behavior. Description adds critical details: truncation at 200K chars with flag, embedding model (BGE-base-en), window size (500-char overlapping), cosine similarity, and return structure (offsets, scores). No contradictions.

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

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

The description is concise (~150 words), front-loaded with purpose and usage, and structured into key sections (when to use, pairing, technical details). Every sentence adds value.

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

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

Given no output schema, description adequately explains return format (passages with offsets and scores), behavior on large inputs, and pairing with another tool. No gaps for a semantic search 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?

Input schema has 100% coverage with descriptions. Description enriches parameters with concrete examples (e.g., query examples like 'supply-chain risk') and clarifies the text parameter's source. Slight improvement possible on limit range, but the default is clear in 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 fetched record, with specific examples (SEC 10-K, article, tool result). It differentiates from sibling tools like ask_pipeworx_grounded by explaining how they pair together.

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 (record too big for prompt) and when to use alternatives (ask_pipeworx_grounded for grounded responses). Provides clear context for selecting this tool over others.

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 contradicts the idempotentHint annotation: the tool creates a new subscription each time, which is not idempotent. Additionally, while it adds useful behavioral details (e.g., delivery caps, phone verification), the contradiction is a significant issue. The description does not clarify idempotency.

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

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

The description is well-structured with clear sections, but it could be more concise. The front-loaded purpose is good, but the length might be overwhelming. Most information is valuable.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers required/optional parameters, auth requirements, delivery options, caps, type-specific filters, and even signing details for webhooks. Nothing obvious is missing for an agent to use it correctly.

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

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

Schema coverage is 100%, and the description adds substantial meaning beyond the schema, including concrete examples for each subscription type and detailed delivery channel explanations. It improves schema understanding without redundancy.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (Create) and resource (subscription), and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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 rich context on when to use the tool, including the requirement for a Pipeworx OAuth account ('anonymous + BYO cannot persist subscriptions'), supported types with examples, and delivery channel options. However, it does not explicitly state when not to use this tool or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant detail: returns category-bucketed examples with tool shapes, drawn from live catalog, and optional topic filtering. No contradictions.

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

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

Well-structured with front-loaded example queries, then functional description. Slightly verbose but every sentence adds value. Could be tightened, but still effective.

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 param, no output schema), the description gives adequate context about return values (category-bucketed examples with tool shapes). No further details needed for an onboarding 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 a parameter description. The description adds meaning by listing example topic values (finance, pharma, etc.) and explaining the effect of providing or omitting the parameter.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It uses specific verbs ('returns', 'answer') and distinguishes from siblings like ask_pipeworx by being the 'first' tool to use.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists example queries. Context is clear, but no explicit when-not-to-use or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the external data source (pypistats.org) and the output structure (per-OS download counts), exceeding 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 two concise sentences, front-loaded with the core action and scope. No redundant words.

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

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

Given the tool has an output schema (not shown), the description need not detail return format. It covers the source, action, and output structure. Could mention that the breakdown is by OS, but it already does.

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 0%, meaning the description does not describe the 'package' parameter. While the description mentions 'a package', it does not explicitly state that the parameter is the package name or provide details. With only one parameter, more clarity is expected.

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 fetches PyPI download breakdown by OS from pypistats.org, with specific verb 'Fetch' and resource 'PyPI download breakdown for a package'. It distinguishes from sibling tools like python_major or python_minor by focusing on per-OS data.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. The purpose is implied but not elaborated.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that the row is deactivated (not deleted) so historical events remain available, which is valuable behavioral 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?

Two sentences, no waste. The key action ('Cancel a subscription') comes first, followed by essential behavioral details. 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 tool with one parameter and no output schema, the description fully covers purpose, ownership constraint, and the deactivation behavior. Nothing essential is missing.

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

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

Schema coverage is 100% with a description for 'id.' The description adds that the id is returned by subscribe, providing helpful context about how to obtain the parameter 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 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by 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 explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding agents on proper use. It does not explicitly mention when not to use or suggest alternatives, but the context is clear enough.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral nuances: it explains that `could_not_verify` means the check did not happen and must not be interpreted as evidence, and that `unsupported` means no source was covered. It also reveals the two internal pipelines (structured vs. grounded) and that the tool replaces 4–6 sequential calls. These details materially enhance the caller's understanding of what the tool does and how to interpret its results.

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 appropriately sized for a tool of this complexity, with a clear structure: examples first, then usage, routing logic, return values, and critical caveats. Every sentence adds value—there is no filler or repetition. It is front-loaded with natural-language examples that immediately convey intended use.

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

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

Given the lack of an output schema, the description fully explains the return value structure (verdict enum, actual value with citation, reasoning) and explains edge-case verdicts (`could_not_verify`, `unsupported`). It also covers the tool's behavior across different claim types and the routing to structured vs. grounded pipelines. This is complete for an agent to invoke the tool correctly and interpret results without additional context.

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

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

The input schema has 100% coverage with detailed descriptions for both `claim` and `tolerance_pct`, including examples and default behavior. The main tool description, however, does not add any additional parameter semantics beyond what the schema already provides. Since schema coverage is complete, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, returning a verdict. It uses specific verbs like "verify" and "fact check" and explicitly describes the output (verdict, actual value, reasoning). This distinguishes it from siblings like ask_pipeworx_grounded, which is a general grounded Q&A tool, whereas validate_claim is narrowly focused on validating factual claims with a structured verdict.

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

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

The description provides explicit usage guidance: "Use whenever the agent needs to check whether something a user said is factually correct." It also details two distinct routing paths (SEC EDGAR for company-financial claims, grounded pipeline for others), which helps callers understand when this tool applies. However, it does not explicitly name alternative tools to use instead or mention when not to use it, 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.