Pypi

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds context: default model (free), optional Anthropic probe, and 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 a single dense paragraph, but every sentence adds value. It front-loads the main action. Could be slightly restructured for easier scanning, but no wordiness.

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 4 parameters, no output schema, and medium complexity, the description covers return shape, use cases, and API key requirement. Could detail scoring interpretation, but overall is sufficient.

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

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

Schema description coverage is 100%, and the description adds meaning: default model (Workers AI Llama-3.3-70b free), _apiKey passed to Anthropic, context for disambiguation. This enriches understanding beyond the schema.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business / brand / product / topic') and clearly distinguishes it from sibling tools by focusing on multi-model visibility scoring.

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

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

The description explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when the _apiKey is needed. It does not explicitly state when not to use or how it differs from sibling tools, but the purpose is distinct.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it routes questions to external tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also notes 'one fast call' and 'works on every tier'. 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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and is structured logically: purpose, usage triggers, examples, hierarchy, and alternatives. It is somewhat long, but every sentence contributes to effective tool selection. Some redundancy exists (e.g., repeated mention of web search), but not to the point of waste.

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

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

Given the tool's complexity and the lack of an output schema, the description is exceptionally complete. It explains the tool's purpose, the types of questions it handles, its routing mechanism, output format (structured answer with citations), and when to escalate to sibling tools. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with six aliases for 'question', all described in the schema. The description enriches parameter semantics by providing example questions and trigger phrases, even though it adds no syntax details. The baseline is 3 for high coverage, but the examples and guidance push it to 4.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explaining when each is appropriate.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives. It gives trigger phrases ('what is', 'look up', 'find', etc.) and concrete examples, making it clear when to use this tool versus web search or 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 annotations (read-only, idempotent, non-destructive), the description discloses that this is an experimental beta with candidate routing improvements enabled live, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. It also reveals that usage results inform merge decisions, providing valuable behavioral context.

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

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

The description is four sentences, each contributing useful info: what it is, current state, usage instruction, and reassurance that it's a full router. The specific retirement date adds minor verbosity but the overall structure is front-loaded and purposeful.

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 universal router, the description adequately covers the experimental nature, current state, and usage guidance. It doesn't detail the response format, but it explicitly states it matches ask_pipeworx's response shape, which is sufficient given the complete schema and 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?

The input schema has 100% coverage, documenting the required 'question' parameter and all five aliases. The description adds no parameter-specific information, so it meets the baseline but does not exceed it.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router handling 5,529 tools. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing experimental routing improvements and explicitly stating it is 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 gives explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that there is no fallback because it is a full working router, and notes that results are compared against the stable router to decide merges.

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?

Goes well beyond annotations by describing exact return shape: {answer, evidence (verbatim quote), confidence, source, fetched_at, refusal_reason:null} and failure modes with refusal_reason enum values. It also discloses the extra LLM call and the 'ONLY what the tool result contains' constraint. No contradiction with readOnly/openWorld/idempotent hints; in fact, the description reinforces 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?

Every sentence earns its place: purpose, routing behavior, return format, refusal reasons, use cases, cost trade-off, and preference for sibling. Despite being longer than typical descriptions, it's densely packed with actionable info and well-structured with dashes and bullet-like lists.

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

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

Given no output schema, the description compensates fully by specifying exact return fields and refusal reasons. It covers use cases, performance cost, and alternative tool. The complexity of routing across 5,529 tools is summarized without overwhelming detail. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with the question parameter and aliases already described. The description adds value by explaining that the question is used for routing and argument-filling across thousands of tools, which gives context to the parameter semantics. However, it doesn't dive into formatting or length expectations, so a 4 rather than 5.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies that it routes like ask_pipeworx but extracts answers using only tool results, distinguishing it from the sibling ask_pipeworx. The verb 'EXTRACTS' and resource 'answer' with evidence and refusal handling are 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?

Explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' Also mentions cost trade-off ('costs one extra LLM call'), giving clear decision guidance relative to the sibling 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?

Discloses extensive behaviors beyond annotations: fan-out to specific data sources, resolver contract with confidence scoring, parent event extraction, news fallback mechanisms, safety short-circuits for low confidence, closed market handling, wide spread warnings, and cancellation rule parsing.

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?

Description is long but well-organized with section headers and examples. Every sentence adds value, though slight trimming could improve conciseness without losing content.

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

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

Thoroughly covers all aspects given no output schema: response shapes, resolver contract, parent event extractor, news fields, safety checks, closed markets, wide spreads, and cancellation rules. No apparent 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 critical meaning: market parameter accepts slugs, URLs, or question text; depth parameter explains quick vs thorough; include_raw explains summary vs full payload with size context.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb 'research' and resource 'bet'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on data gathering and analysis.

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

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

Explicitly states use cases like 'should I bet on X', but lacks explicit when-not-to-use or direct alternative references. Context from sibling tools implies alternatives, but not spelled out.

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

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

The annotations (readOnlyHint, idempotentHint, etc.) indicate safe, non-destructive behavior. The description adds rich behavioral context: for company type, it pulls real financial data from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drug type, it pulls adverse-event and approval counts. It also mentions sorting by primary metric and returning citation URIs. No contradictions with annotations.

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

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

The description is concise (around 100 words) and front-loads the core purpose with query examples. It is structured with clear separation of company vs drug behavior and ends with a summary of benefits. Some redundancy exists ('ALWAYS PREFER' is emphasized), but overall every sentence contributes meaning without excessive verbosity.

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

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

Given the tool's complexity (two entity types, multiple data sources) and no output schema, the description covers key behavioral aspects: data origin, financial metrics, drug metrics, sorting, and citation URIs. It also mentions edge-case handling (off-calendar fiscal years). It does not explain error cases or rate limits, but annotations cover idempotency and read-only nature. Overall well-rounded.

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, baseline is 3. The description adds significant meaning beyond the schema: it explains that 'values' should be tickers/CIKs for company type and drug names for drug type, and it specifies the allowed count range (2-5). It also clarifies the effect of the 'type' parameter on data sources and output. This adds value beyond the bare schema.

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

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

The description uses specific verbs like 'Compare', 'rank', and 'head to head' and clearly states it produces side-by-side comparisons of 2-5 companies or drugs. It distinguishes from siblings by explicitly noting it replaces 8-15 sequential lookups and should be preferred over single-pack lookups. The examples of natural language queries further clarify the tool's purpose.

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

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

The description explicitly says when to use this tool (for comparisons of multiple entities) and strongly urges preference over sequential single-pack lookups. It provides example query patterns. However, it does not explicitly state when NOT to use it (e.g., for single entity queries), though the sibling tool 'entity_profile' exists. Still, the guidance is clear and actionable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavior: account/paid-plan requirements, parallel decomposition, explicit gaps[] for unanswered facets (never invented), always-fetchable citation_uris, contradictions[] for standard/thorough, semantic excerpting of long records, and expected latency. This adds substantial context far beyond the structured metadata.

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

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

The description is long but front-loaded with the most critical constraints (account requirement, alternative) and organized into logical segments (purpose, use cases, depth behavior, return format). It earns its length given the tool's complexity, though there is minor redundancy with the schema's depth description that keeps it from a perfect score.

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

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

With no output schema, the description fully explains the return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] behavior, contradictions[], hop and citation_uri fields, and latency expectations. Combined with account/plan notes and depth distinctions, it leaves no operational ambiguity.

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%—both `depth` and `question` already have detailed descriptions in the schema, including depth-specific facet counts and behavior. The description largely reiterates this same information without adding new parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: multi-source research across Pipeworx's 1455 structured data sources, decomposing questions and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, leaving no doubt about its scope and primary 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?

The description provides explicit when-to-use and when-not-to-use guidance, including specific alternatives: use ask_pipeworx for single lookups and breaking/current news, and use deep_research only when signed in (otherwise ask_pipeworx works on every tier). It also explains depth selection trade-offs, making the appropriate context for each option 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by disclosing that results are 'ready to call directly, no second schema lookup needed' and that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' 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 the core purpose, then immediate usage guidance. Every sentence is meaningful with no 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?

Combined with comprehensive annotations (safety, idempotency) and full schema coverage, the description completes the picture: it explains purpose, usage, output structure, and distinguishes itself from 35+ sibling tools. No output schema needed as description covers return format.

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 clear descriptions for all 6 parameters. Description adds extra value by noting that query accepts multiple aliases (q, task, search, description) and specifying default/max for limit.

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 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, financials, FDA drugs, etc.), distinguishing it from sibling tools that perform specific tasks. It establishes the tool as a discovery mechanism.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides context for when to browse/search/discover. Does not explicitly state when NOT to use, but the guidance is strong enough for an 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: lists data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields, notes patent soft-fail and GDELT→GNews fallback, and clarifies input restrictions. 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 somewhat lengthy but highly informative. It is front-loaded with example queries and key purpose. Each sentence contributes unique information, though minor trimming of examples could improve conciseness without losing clarity.

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 output schema, the description comprehensively covers inputs, data sources, return structure, limitations (patents sunset, names not supported), and fallback behavior. It addresses all foreseeable context needed for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description enhances parameter meaning: explains type is limited to 'company', value accepts ticker or zero-padded CIK, and explicitly states names are not supported. This adds significant clarity beyond the enum and description 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 starts with example user queries and clearly states 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates from related tools by recommending this tool over chaining individual lookups and mentions alternatives like resolve_entity for names-only inputs.

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 for holistic company profiles and when-not-to-use for names (directing to resolve_entity) or for person/place (coming soon). It also contrasts with alternative approaches like chaining single-source 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, readOnlyHint=false, and idempotentHint=true. The description adds no further behavioral context beyond 'delete', which matches 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?

Two concise sentences with no extraneous information. Front-loaded with the core action.

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

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

Given the single parameter, no output schema, and complete annotations, the description provides all necessary context for an agent to use the tool.

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

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

Schema coverage is 100% with a clear description for 'key'. The description adds no additional meaning beyond the schema's definition.

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', specifying the action and resource. It distinguishes from sibling tools by mentioning 'remember and recall'.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Lacks explicit when-not or alternatives, but the mention of sibling tools provides context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context on actions: fetches page, extracts title/description/key links, emits markdown. This enriches understanding beyond annotations, though annotations cover safety and 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 a single paragraph of three sentences, front-loading the main purpose and output. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for use cases).

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

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

Despite no output schema, the description specifies the output format (single text blob, standard llms.txt markdown). Parameters are fully documented in schema. The tool is simple, and the description covers all necessary context for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions 'for any URL' and 'default 25, max 50' for max_links, which aligns with schema but adds no extra meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb and resource. It distinguishes from siblings by focusing on llms.txt generation, a unique task among the listed sibling tools.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor AI crawler view. It does not provide when-not-to-use but offers clear positive guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the external data source (pypistats.org) and the specific time ranges returned, providing context beyond the annotations.

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

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

The description is concise, using two short sentences. It front-loads the action and key details, with no redundant or unnecessary 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 the tool's simplicity (one parameter, no output schema), the description is complete. It explains what the tool does, what data it returns, and its source. Annotations cover safety, so no further elaboration is needed.

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

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

The input schema describes the single parameter 'name' fully (100% coverage). The description does not add additional semantic information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'recent download counts', and specifies the time ranges (last day, last week, last month) and source (pypistats.org). It also indicates the tool's purpose of gauging pip package popularity. No sibling tool has a matching 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 implies usage for checking package popularity via 'Gauges how popular a pip package is.' However, it does not mention when not to use this tool or suggest alternative tools for related tasks like package metadata retrieval.

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 no destructiveness. The description adds value by detailing the returned metadata (version, summary, keywords, etc.), helping the agent understand the output.

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 the core purpose, 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, the description sufficiently covers what the tool returns, and the annotations cover safety. The tool definition is complete for the agent.

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

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

Schema coverage is 100% and the parameter description is already clear. The description reiterates the example, adding little extra 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 retrieves metadata for a Python package on PyPI, listing specific fields (latest version, summary, etc.). It distinguishes from siblings like get_package_version.

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

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

It instructs to pass the exact pip package name, providing clarity on input. While no explicit alternatives are given, the purpose is specific enough for an agent to infer when to use.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds value by listing the specific data returned (summary, Python version, dependency list, downloadable files), which gives the agent a clear expectation of the response content.

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

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

The description is three concise sentences: one for purpose, one for contents, one for usage example. Every sentence is meaningful and well-structured, with 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 no output schema, the description adequately explains what is returned. It does not mention error cases or limitations, but for a simple metadata lookup with strong annotations, it is sufficiently complete.

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

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

The input schema already has 100% coverage with clear descriptions for both parameters. The description does not add additional semantics or constraints beyond what the schema provides, so it meets the baseline without extra value.

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

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

The description clearly states it retrieves metadata for a specific version of a Python package from PyPI, with a list of returned fields. It is explicit about the verb and resource, but does not explicitly differentiate from sibling tools like 'get_package' or 'list_releases', though the version-specific nature is implied.

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 a usage example ('Use to inspect a pinned release like requests 2.31.0'), indicating when to use it. However, it does not mention when not to use it or point to alternative tools for other scenarios (e.g., getting latest version).

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. The description adds that results are sorted and includes the latest version, providing useful 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 with no wasted words. Front-loaded with the action verb and resource, followed by use case examples.

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, no output schema, and strong annotations, the description is sufficient. It captures key behavior and use cases, though output format is not detailed.

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

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

Schema coverage is 100% with a clear description for the 'name' parameter. The tool description does not add further parameter-level details, 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?

Description clearly states the tool lists all published version strings for a Python package on PyPI, sorted, plus the latest version. It differentiates from siblings like get_package and get_package_version by focusing on the entire release history.

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 says it's useful for seeing release history or checking available versions. It doesn't explicitly mention when not to use or alternatives, but the context of sibling tools makes it clear.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds return field details (id, type, params, etc.), offering moderate 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 concise sentences, front-loaded with the main purpose. Every sentence adds value with no wasted words.

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

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

For a simple, read-only listing tool with one parameter and no output schema, the description is fully complete: purpose, field details, and usage guidance are all covered.

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

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

Schema coverage is 100% with one parameter fully described. The description does not add significant meaning to the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the action (list) and resource (subscriptions), specifying it returns active subscriptions and listing the fields. It distinguishes 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?

The description provides explicit usage scenarios: review before adding more subscriptions or find an id to cancel. It implies alternatives (subscribe, unsubscribe) but does not explicitly state when not to use.

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

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

The description discloses several non-obvious behaviors beyond annotations: rate limit of 5 per identifier per day, claim_token retrieval mechanism for reading resolution status, free/no-quota usage, and that the team reads digests daily. These add real behavioral context not available from annotations or 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 earns its place: purpose, when-to-use, cross-server exclusion, token workflow, rate limit, and quota impact. It is front-loaded with the core purpose, then expands with necessary nuances. No redundant or filler content.

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

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

For a tool with no output schema and moderate complexity, the description covers all necessary context: expected input content, return behavior (claim_token), follow-up usage, rate limits, and scope boundaries. An agent could correctly select and invoke this tool without further clarification.

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

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

Schema already provides 100% coverage of all 4 parameters, so baseline is 3. The description adds extra meaning by explaining the claim_token round-trip flow ('Filing without an account returns a claim_token; pass it back later...') and gives context for message specificity ('don't paste the end-user's prompt'). This pushes it above baseline, though it doesn't deeply detail each param beyond schema.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately enumerates feedback types (bug, feature/data_gap, praise), which distinguishes it from all sibling tools like ask_pipeworx or discover_tools that serve different purposes.

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 (bug, feature/data_gap, praise) and when not to (for tools from other MCP servers), naming the alternative action ('file it with that server instead'). Also provides practical guidance on identifying Pipeworx tools and phrasing feedback. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: caching behaviour (5min-1h), data source (CF analytics-engine), and no PII. This supplements annotations without contradiction.

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

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

The description is concise (5 sentences), front-loaded with the core functionality, and structured with bullet-like use cases. Zero fluff; 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?

The description covers return content (top tools, packs, call volume), caching, and data provenance. While there is no output schema, the description provides sufficient context for agent decision-making. Minor gap: no explicit mention of response format.

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 enum values. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This clarifies the trade-off beyond the schema's static description.

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

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

The description clearly defines the tool's purpose: returning top tools, packs, and call volume over recent windows. It uses specific verbs ('Returns') and resources ('top tools, top packs, and total call volume'), distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Three explicit use cases are provided (discovering hot data, confirming popular tools, checking alignment). While it does not explicitly state when not to use, the context makes the intended usage clear. No alternative tools are named, but the use cases guide appropriate invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: scans top ~200 markets, walks child markets, checks date-axis/threshold-axis ordering, computes partition_check, uses semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs, null if >20% placeholder), and fill check against live CLOB depth. It discloses constraints like skipped_low_similarity and thin_legs. 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 somewhat lengthy but well-structured with paragraphs for each mode and additional details. Every sentence provides actionable information; there is no filler. It could be slightly more concise by grouping some details, but it remains clear and front-loaded with the main purpose.

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

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

Given the tool's complexity (multiple modes, conditions, response structure) and the absence of an output schema, the description thoroughly explains the response format: opportunities[] with fields like gap_pp, suggested_trade, reasoning, and partition_check with gap_from_1, placeholders_filtered, etc. It also covers fill_check and references a sibling tool for custom sizing. The description is complete for an AI to use effectively.

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

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

Schema description coverage is 100% (both parameters documented). The description adds significant meaning beyond the schema: explains acceptable event slug formats ('fed-decision-may-2026' and full URLs), provides seed question examples for topic, and clarifies behavioral differences between modes. This adds substantial value beyond the basic schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args (trending_scan), event (single event slug), and topic (cross-event). The verb 'Find arbitrage opportunities' plus the specific mechanisms and mode differentiation provide excellent purpose clarity.

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 each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It mentions an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is comprehensive.

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, and idempotentHint, which the description complements with extensive behavioral details: caching (1h at KV level), the three model families with mathematical specifics, filter effects, and diagnostics for empty segments. There is no contradiction with annotations.

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

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

The description is long and dense, front-loading the purpose but then delving into deep technical details about model families and segments. While thorough, it could be more concise by moving some details to a separate section. It earns its sentences, but not all are maximally concise for an AI agent reading.

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 (9 parameters, no output schema, rich behavioral traits), the description thoroughly covers output structure (by_segment, diagnostics), explains why segments might be empty, and details edge measures and filter effects. An AI agent has enough context to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default values (e.g., slippage_pp 0.3, max_spread_pp null) and providing nuanced guidance (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). This goes beyond the schema's limited 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return), resource (Polymarket markets), and differentiates from siblings by detailing the three response segments and the underlying models.

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

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

The description provides strong usage context, calling it 'Built for "what should I bet on today"' and explaining the segments and filter knobs. It mentions that Fed bets are excluded from ranking. However, it does not explicitly advise when not to use this tool versus sibling tools like polymarket_arbitrage or polymarket_edge_tracker, though the detail implies a daily scanning use case.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral detail beyond annotations, including the response structure (tracked, expired, snapshot_dates), decay computation details, window family handling, snapshot TTL, and limitations (e.g., daily closes, not intraday). 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 front-loaded with the key question and uses a clear structure with sections for response fields. While lengthy, every sentence contributes useful information. Minor improvement would be to tighten some 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 no output schema, the description thoroughly explains all return fields (tracked, expired, snapshot_dates) with their semantics. It also covers limitations (snapshot TTL, decay computation) and provides enough context for the agent to understand the tool's role relative to siblings. Complete for its complexity.

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

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

Schema coverage is 100%, so the description adds value by explaining the default and max values for 'days' and the meaning of 'window' families. It also provides context about snapshot caching behavior, which is not in the schema. However, the description repeats some schema info, so it's not fully additive.

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

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

The description clearly states the tool tracks edge persistence and decay, answering the specific question of how long an edge has existed and whether it's shrinking. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on time-series analysis rather than current edges.

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

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

The description provides strong context for when to use this tool (e.g., distinguishing a fresh wide edge from an old one), but does not explicitly state when not to use it or name alternatives. It gives implicit usage guidance through the contrast with 'polymarket_edges'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds detailed behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), explains basket behavior, and highlights forced directional risk. No contradiction with annotations.

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

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

The description is fairly lengthy but well-structured with clear sections (single-market vs basket). Every sentence adds necessary information for a complex tool. While it could be slightly more concise, the structure aids readability and the detail 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?

Given no output schema, the description thoroughly explains all return fields for both modes, including verdicts, capture ratios, thin legs, and forced directional risk. It also covers edge cases like partial fills and large trades, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, yet the description adds significant meaning: it explains the side default and auto logic for basket mode, size_usd interpretation differences between buys/sells and single/basket modes, and provides context for each parameter beyond the schema's terse 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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It explicitly distinguishes two modes (single-market and basket) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risk of partial fills converting an arb into a directional position, giving clear context for use.

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

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

The description thoroughly explains the tool's behavior beyond annotations: multiple modes, response structure, compatibility warnings, temporal alignment, and skipped leg counters. 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 thorough but verbose, with some redundancy (e.g., compatibility warning explained twice). It is well-structured with bolding and section headings, 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 no output schema, the description fully explains the return fields (leg prices, spreads, safety fields) and edge cases (mismatched event shapes, temporal misalignment). Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes and the meaning of each parameter, including example topic values and that explicit parameters override topic-mapped side.

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 computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by focusing on inter-venue comparison, not intra-venue arbitrage.

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

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

The description clearly explains two modes (topic shortcuts and explicit tickers) and provides guidance on when spreads are meaningful (temporal alignment, matched pairs). It warns that most pre-mapped topics may not be tradeable, but does not explicitly compare to alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping context ('anonymous IP, BYO key hash, or account ID') and behavior when omitting key, which provides value beyond annotations.

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

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

The description is two sentences, front-loaded with the core action, followed by usage examples and scoping. Every sentence adds value, and there is no fluff.

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

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

Given the tool's simplicity (one optional param, read-only, no output schema), the description covers purpose, usage context, scoping, and pairing with siblings. 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?

The input schema already fully describes the single parameter (key) with a description. The description repeats that omitting key lists all keys but adds no new semantics. With 100% schema coverage, 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 retrieves a value saved via 'remember' or lists all keys if no key is provided. It uses specific verbs and distinguishes from siblings ('remember' for saving, 'forget' for deletion).

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

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

The description provides explicit examples (target ticker, address, research notes) and mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context, such as the effect of setting mark_read:true to flag events as read, and the structure of returned data. 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?

Three sentences efficiently convey the tool's action, return content, and key parameters. The most critical information (what the tool does and returns) is front-loaded. Minor redundancy could be trimmed, but overall well-structured.

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

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

Given the tool's moderate complexity, rich annotations, and full schema coverage, the description adequately covers return fields (source, citation_uri, payload) and the mark_read behavior. The absence of an output schema is mitigated by explicitly stating return structure. An alternative access URL is provided for external use.

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

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

With 100% schema coverage, the description still enriches parameter meaning by providing examples ('e.g. sec_8k'), clarifying the ISO timestamp format for 'since', and explaining the side effect of 'mark_read:true'. 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 a specific verb ('pull fired events') and clearly identifies the resource ('your subscription feed'). It states the exact return fields (source, citation_uri, payload) and filter options, making the tool's purpose unambiguous and distinct from siblings.

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

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

The description explains when to use the tool ('Polls work fine') and mentions an alternative access method ('same feed at GET registry.pipeworx.io/alerts.json for scripts and dashboards'). It provides examples of filter usage but does not explicitly exclude scenarios where other tools would be better.

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

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

Discloses internal fan-out to multiple sources, fallback logic, and known API sunset. Describes return structure (changes[], total_changes, URIs). Adds substantial context beyond annotations (readOnlyHint, etc.).

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 of ~90 words, front-loaded with examples. Every sentence contributes: purpose, sources, fallback, parameter guidance, and alternative tool. No redundant or irrelevant content.

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

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

Despite no output schema, the description explains the return structure (grouped changes, counts, URIs). Covers behavior, parameters, sources, fallback, and alternatives. Fully adequate for a tool with good annotations and 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?

All three parameters are fully described in schema (100% coverage). Description adds examples, explains 'since' formats (ISO date and relative shorthand), suggests typical monitoring value ('30d' or '1m'), and clarifies acceptable formats for 'value' (ticker or CIK).

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 change feed for a company in one parallel call, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling tool entity_profile, making purpose unambiguous.

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

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

Provides natural language query examples and explicit guidance to use entity_profile for static profiles. Explains fallback behavior. Lacks explicit 'when not to use' beyond the one alternative, but sufficient for decision-making.

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

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

Annotations (idempotentHint=true, destructiveHint=false) are present. The description adds significant behavioral context: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. Does not contradict annotations.

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

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

The description is front-loaded with the main purpose and is well-structured. Every sentence adds value, though slightly verbose. Still concise for the information provided.

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

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

Given the simple tool (2 required params, no output schema), the description is complete. It explains storage scope, persistence duration, and pairing with siblings. 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 has 100% coverage with descriptive names and examples. The description adds typical key pattern examples (e.g., 'subject_property', 'target_ticker') and clarifies the value is any text, adding context beyond the schema.

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

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

The description clearly states the tool's function ('Save data the agent will need to reuse later') with specific examples (resolved ticker, target address, user preference) and distinguishes it from siblings recall and forget by mentioning pairing.

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 specifies when to use ('when you discover something worth carrying forward') and provides examples. Also indicates pairing with recall for retrieval and forget for deletion, guiding the agent on usage 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?

Beyond the read-only/idempotent annotations, the description details that unresolved identifiers are explicitly listed under 'unresolved', LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. This adds significant behavioral context without contradicting any 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 front-loaded with the core purpose and examples. It uses a 'SUPPORTED TYPES' structure to organize details efficiently. Every sentence adds value, though it could be slightly trimmed 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 the complexity of cross-source identity resolution and the lack of an output schema, the description thoroughly explains what is returned (CIK, ticker, LEI, FIGI, RxCUI), source attribution, fallback behavior, and unresolved indicators. It is highly self-contained and leaves little ambiguity.

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

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

Schema coverage is 100%, so parameters are documented, but the description adds concrete examples (AAPL, 0000320193, ozempic) and clarifies input formats for each type. It also explains nuances like FIGI resolution 'when a ticker is implied', which goes beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with multiple concrete query examples. It explicitly distinguishes itself as the first-choice tool for name-to-ID needs, setting it apart from sibling tools like entity_profile.

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

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

It provides an explicit directive 'Use FIRST whenever you have a name but need an ID' and describes supported types and accepted inputs. However, it does not explicitly mention when not to use the tool or directly compare with alternatives, so it falls just short of a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint. Description adds that it probes entities with ai_visibility_check, ranks results, and returns specific fields (score, confidence, signal density). 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?

Three sentences, front-loaded with action, no unnecessary words. Efficiently conveys purpose, method, and output format.

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?

Covers input semantics and output format well. Lacks error handling or edge cases, but given simplicity and good annotations, it is sufficient for effective use.

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

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

Schema coverage is 100% with descriptions. Description adds semantic value: explains 'entities' (first entry as subject), 'context' for disambiguation. Provides meaningful usage guidance beyond schema.

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

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

Description uses specific verb 'Compare' and resource 'AI visibility across multiple entities', clearly distinguishing from sibling ai_visibility_check which handles single entities. Provides concrete use case example.

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

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

Explicitly states use case: 'competitive AI-marketing audits' and implies alternative by referencing ai_visibility_check. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list. 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?

Description is somewhat verbose but well-structured; front-loaded with purpose. Could be more concise but effectively communicates key information in 3-4 sentences. 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 complexity (multiple data sources, fallbacks, timing), description covers return fields (summary block, advisories, links, alternative versions) and failure behavior. No output schema, but description sufficiently informs agent of expected 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?

Schema description coverage is 100% with clear parameter descriptions. Description does not add significant extra parameter meaning beyond what schema provides. Baseline 3 applies.

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

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

Description clearly states composite check for npm package covering safety, size, and popularity. Distinct from siblings like get_package and get_package_version, which are simpler lookups. Specifies ecosystem scope (npm only in v1).

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

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

Explicitly states when to use: when agent asks 'is X safe/popular/small' or 'what does adding X cost'. Also notes limitations: NPM only; other ecosystems fall under different tool. Provides alternative guidance for other ecosystems.

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

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

The description adds substantial context beyond annotations: chunking strategy (BGE-base-en, 500-char windows), character limit (200K chars with truncation flag), and return format (passages with offsets and similarity scores). Annotations only declare readOnlyHint, openWorldHint, etc.

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

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

Two well-structured sentences plus technical details in a concise paragraph; front-loaded with the primary action, no extraneous content.

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

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

Covers all essential aspects: purpose, usage, pairing, technical details, and return value (offsets, scores). No output schema exists, but the description adequately describes the output.

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

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

Schema coverage is 100%, but description adds value by clarifying the max chars for text, providing example queries, and explaining the limit parameter. A baseline of 3 is exceeded.

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 specifies 'semantic search INSIDE a fetched record' with a clear verb and resource, and distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the pairing pattern.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt', and suggests pairing with ask_pipeworx_grounded, providing clear context for alternatives.

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

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

The description adds significant behavioral context beyond annotations: it details the need for account verification for SMS, the 10/day cap on SMS, the always-on feed channel, and the webhook auto-disable after 10 failures. These are not present in annotations and provide critical transparency for tool invocation.

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 main purpose and returns information. Each sentence serves a purpose, covering prerequisites, types, and delivery channels without redundancy. It is concise yet comprehensive.

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

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

The description covers most aspects: returns the subscription id, prerequisites, delivery channels, and three main types. However, it does not explicitly mention the other two types (patent_grant, clinical_trial) listed in the schema, which would be needed for full completeness given the tool's complexity and no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples (e.g., sec_8k items, polymarket_edge topic) and clarifying requirements (e.g., phone verification, daily caps) that enrich the bare 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 'Create a proactive monitoring subscription' and identifies the resource as a 'live-data event stream'. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by emphasizing proactive monitoring and alert delivery.

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

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

The description explicitly states the prerequisite of a Pipeworx OAuth account and that anonymous/BYO users cannot persist subscriptions. It also provides type-specific parameters and delivery options, implying when to use each subscription type. However, it does not explicitly exclude use cases or compare directly to 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=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context about the output structure (category-bucketed example questions) and that it draws from the live catalog. 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 front-loaded with the purpose and uses a single paragraph. Every sentence adds information, though it is slightly longer than necessary. It 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?

Despite having no output schema, the description fully explains what the tool returns (example questions with tool+argument shapes), how to use it (no args or with topic), and when to use it (first when onboarding). It is complete for its complexity.

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

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

The schema has one optional parameter with enum-like description. The description adds context that omitting it gives a cross-category spread and lists example topics, which adds meaning beyond the schema. Schema coverage is 100%, so baseline is 3; description adds value.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs like 'returns' and distinguishes itself from siblings as the first tool to use when unsure.

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

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

The description explicitly says to use this FIRST when you don't know what Pipeworx can do, and gives guidance on calling with no arguments for full spread or passing a topic to focus. It does not explicitly exclude 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?

Description adds value beyond annotations by explaining deactivation (not deletion) and historical availability via 'recent_alerts', which supplements the idempotentHint and destructiveHint annotations without contradiction.

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

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

Two concise sentences: first states the action, second explains behavior. No redundant or extraneous information.

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

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

For a simple single-parameter tool with annotations present, the description covers ownership, deactivation, and downstream impact on historical events, making it fully contextual.

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

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

Schema coverage is 100% and the description does not add extra semantics beyond what the schema already provides for the 'id' parameter (e.g., 'returned by subscribe'). Baseline score is appropriate.

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

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

Description clearly states action 'Cancel a subscription by id' with specific verb and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Description mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. However, it does not explicitly state when not to use or name alternative tools for other scenarios.

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

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

The description goes well beyond annotations by explaining the meaning of each verdict, especially the critical distinction between could_not_verify and unsupported. It clarifies that could_not_verify is not evidence and must not be presented as one. Annotations already indicate read-only, open-world, idempotent behavior, which the description does not contradict.

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

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

The description is a single dense paragraph, but every sentence serves a purpose: examples, usage, pipeline breakdown, return values, and a caveat. It is longer than strictly necessary but front-loaded with examples and clear usage guidance. A bulleted structure might improve readability.

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

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

Given no output schema, the description fully explains the return value (verdict types, actual value with citation, reasoning) and error semantics (could_not_verify vs unsupported). It also covers the two backend paths, making it sufficient for an agent to understand and invoke the tool correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters (claim and tolerance_pct). The description adds no additional parameter guidance beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It gives concrete example phrases and distinguishes it as a fact-checking tool, unlike generic sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and details the two distinct processing paths (SEC EDGAR for company financials, grounded pipeline for everything else). It also notes the tool replaces 4–6 sequential calls, reinforcing when it is the efficient choice.

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