Paperswithcode

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable details: the return structure (per-model score, confidence, signals, raw_response + combined view) and cost implications (free for Workers AI, BYO key for Anthropic). 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, well-structured paragraph that efficiently covers purpose, default behavior, optional parameters, return format, and use cases. No superfluous words, and key information is front-loaded.

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

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

Despite no output schema, the description clearly outlines the return shape and explains the function of each parameter. It adequately covers the tool's complexity, including dual-model probing and the role of the context parameter.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds context beyond the schema by explaining default model behavior, the optional nature of _apiKey, and the disambiguation benefit of context. This adds value without being redundant.

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 what the tool does: probe LLMs for knowledge about an entity and score visibility from 0-100. It specifies the default model and the optional Anthropic probe. The use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) differentiate it from sibling tools.

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

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

The description explains when to use the tool (for visibility checks) and how to extend it (apiKey for Anthropic). It doesn't explicitly set against alternatives, but the unique purpose and the specificity of usage instructions make 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it routes, fills arguments, and returns structured answers with stable pipeworx:// citations. It does not fully describe edge-case behavior like no-match handling or clarification requests, but it is not misleading.

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 and information-rich, but it contains a large verbatim duplicate block: 'START HERE for most questions... active clinical trials for GLP-1' appears twice. This redundancy makes the description unnecessarily long and each sentence does not earn 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?

Given a single required question parameter and no output schema, the description covers the key selection information: domains, trigger phrases, examples, return shape, and escalation alternatives. It does not document failure or clarification behavior, but that is unlikely to block correct invocation.

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

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

Schema coverage is 100%: the schema documents question and all five aliases, so the description adds little semantic weight. The examples in the description demonstrate valid question formats, but they do not meaningfully extend the parameter semantics already present in the schema.

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

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

The description states a precise role: route a natural-language factual question to the right one of 5,767 tools across 1,506 verified sources and return a structured answer with pipeworx:// citation URIs. It clearly separates this tool from web search and from related tools like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), gives concrete examples, and says 'START HERE for most questions'. It also names the conditions for stepping up to ask_pipeworx_grounded or deep_research.

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

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

Beyond the annotations, the description discloses that this is an experimental router with candidate routing improvements enabled live during tests, that no candidate is currently active, and that it falls back to nothing but is still a full working router. This gives important behavioral context annotations cannot convey.

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

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

The description is appropriately detailed and front-loaded with the beta identity and relationship to ask_pipeworx. It has some slight redundancy in repeatedly saying 'same' for tools, arguments, and response shape, but every sentence contributes useful context.

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 tells the agent the current state, how to use it, what it shares with ask_pipeworx, and what happens when a candidate is under test. There is no output schema, but it points to the shared response shape. It does not fully detail response contents, but this is mitigated by the reference to ask_pipeworx.

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 each parameter already has a description. The tool description mentions the same arguments as ask_pipeworx but adds no additional parameter-level 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 identifies this as a beta variant of ask_pipeworx, states that it is a universal router with the same tools, arguments, and response shape, and explains how it differs from the stable router. This distinguishes it from the sibling ask_pipeworx and other tools.

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

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

The description explicitly says to use it like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It points to the alternative stable router, though it does not explicitly say 'do not use this if you want stable behavior'.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds substantial behavioral detail by specifying the exact success return shape and structured refusal reasons. It also discloses the cost tradeoff. No contradiction with the annotations is present.

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

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

Every sentence delivers a distinct decision-relevant fact: mode definition, routing behavior, return contract, refusal contract, usage trigger, and cost comparison. It is dense but not padded, and the key differentiator is front-loaded.

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

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

Even without an output schema, the description fully specifies the success and failure return contracts, refusal reasons, and operational cost. For a single natural-language-parameter tool, there is no material gap between what an agent needs to call it correctly and what is provided.

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 schema already documents the question parameter and its aliases. The description mentions argument-filling at a high level but adds no parameter-level meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with a specific mode: hallucination-resistant grounded answering, and immediately differentiates it from ask_pipeworx by stating it extracts answers only from tool results rather than generating freely. This makes its role distinct from siblings like ask_pipeworx and validate_claim.

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

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

It gives explicit selection criteria: use when an answer will be quoted, cited, or acted on and facts must not be invented, and explicitly says to prefer ask_pipeworx for casual lookups because of the extra LLM call. This is direct when-to-use and when-not-to-use 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=true, openWorldHint=true, etc. The description adds extensive behavioral context: low-confidence short-circuiting, closed market handling, wide-spread tradeability, resolution-rule risk, and fan-out behavior, all 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?

Long but well-structured with clear sections (response shapes, resolver contract, etc.). Every sentence adds useful detail; no obvious redundancy. Could be slightly shorter but front-loads purpose effectively.

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

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

No output schema exists, so description must explain return values. It thoroughly describes result.market, result.analysis, result.evidence, resolver contract, parent_event extractor, news fields, safety mechanisms, and resolution-rule risk. 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 covers all 3 parameters with descriptions. The description adds value by explaining how to pass market (slug, URL, or question text), and clarifies depth and include_raw defaults and behavior. This exceeds baseline 3.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb 'research' and resource 'Polymarket bet'. It distinguishes from siblings by focusing on data retrieval for a single bet, unlike arbitration or edge tools.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), guiding the agent when to use. Lacks explicit exclusions or alternatives, 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 indicate safe, idempotent, non-destructive behavior. The description adds context about result sorting by primary metric, citation URIs, and handling of off-calendar fiscal years, providing meaningful behavior beyond annotations.

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

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

The description is a single efficient paragraph, front-loaded with trigger phrases and explicit preference instruction. It is comprehensive without being verbose, though a bulleted structure could 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?

For a tool comparing two entity types with multiple data sources, the description covers key aspects: data sources, sorting, citation URIs, and replacement of multiple lookups. No output schema exists, but the return type is indicated ('paired data + URIs'). Minor gaps in exact output structure are acceptable given 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 coverage is 100%, but the description enhances parameter understanding by explaining what data each entity type retrieves (e.g., 'company' from SEC, 'drug' from FAERS) and clarifying that values should be tickers/CIKs or drug names, adding value beyond schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, specifying detailed data sources for each type (SEC financials, FAERS, FDA approvals, trials). It distinguishes from sibling tools like entity_profile by emphasizing that this tool is for multi-entity comparisons.

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

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

The description explicitly advises preferring this tool over sequential single-entity lookups, provides example queries, and clarifies entity types. It does not explicitly list cases when not to use, but the context is clear for comparative tasks.

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

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

Annotations already establish readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable behavioral context: account/auth requirements, paid plan gate for 'thorough', the guarantee that it 'never invented' answers but returns explicit gaps[], and the exact findings packet shape (verbatim evidence, confidence, source, fetched_at, citation). No contradiction with annotations.

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

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

The description is dense and front-loaded, starting with the account requirement and the main alternative. It includes some redundancy ('use ask_pipeworx instead' appears twice for different conditions), but every sentence contributes meaningful operational or selection detail. Slightly longer than minimal, but appropriate for the tool's complexity and lack of output schema.

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

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

Given there is no output schema, the description properly documents the return payload fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]). It also covers auth levels, the fallback tool, source scope, and what the tool is not. For a two-parameter tool with rich schema descriptions, nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by giving example real-world questions ('compare X and Y's regulatory + financial exposure', 'research the filings + market picture for ACME'), clarifying that the question should be broad/multi-part and structured-data-oriented. This helps an agent craft a valid `question`, earning above baseline.

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

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

The description names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call.' It explains the mechanism (decomposes question into facets, routes to 5,767 tools in parallel) and clearly distinguishes itself from open-web search and sibling ask_pipeworx. This is unambiguous about what the tool does.

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

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

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data,' with concrete examples. It also states the exclusion criteria and alternative: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' The agent is told exactly when to pick this tool versus a sibling.

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 transparency by explaining that the tool returns top-N most relevant tools with full input schemas and curated examples, ready to call without a second lookup. This provides behavioral context beyond the annotations.

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

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

The description is well-structured and front-loaded with the purpose. It is somewhat lengthy but every sentence provides useful information, such as examples, return format, and usage guidance. Could be slightly more concise, but overall efficient for the information density.

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 (6 parameters, many aliases), the description is complete. It explains the output format (top-N tools with schemas, ready to call) and provides multiple examples. No output schema exists, but the description covers what to expect. The annotations and schema cover safety and parameters.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters. The description adds value by clarifying that parameters like 'query' accept multiple aliases (task, q, description, search) and gives examples. However, it does not add significant meaning 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 uses a specific verb ('find tools') and clearly identifies the resource ('tools by describing the data or task'). It lists many example domains and distinguishes itself from siblings by being a discovery-oriented tool. The title 'Discover Tools' is reinforced by the description.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies that for specific queries, one might directly call other tools, but does not provide explicit when-not or alternatives. The guidance is clear and contextual.

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

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

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false all present, the safety profile is already clear. The description then goes well beyond annotations by disclosing fan-out behavior, soft-failure of USPTO PatentsView, the meaning of sources_used/sources_failed, empty-section semantics, private-company behavior, and name resolution. This is exactly the behavioral context an agent needs.

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

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

The description is dense and front-loaded with usage triggers, but it is long and somewhat run-on, with many semicolon-separated return-field explanations packed into one paragraph. Every sentence adds substance, yet the structure could be tightened through lists or clearer separation between invocation, return fields, and failure semantics.

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

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

There is no output schema, so the description carries the full burden of explaining return structure. It enumerates every section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) plus sources_used/sources_failed and resolved:false behavior. It also covers edge cases like FDA no-data expectations and soft-failed sources. Nothing practically needed to invoke and interpret the tool is missing.

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

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

Schema coverage is 100%, but the description meaningfully extends the schema by giving concrete example values, explaining zero-padded CIK format, stating that company names resolve via SEC EDGAR, and clarifying that 'company' and 'ticker' are interchangeable. This goes beyond restating the schema and helps an agent construct valid calls.

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

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

The description names a clear verb-resource pair ('full cross-source profile of a US public company'), gives concrete example queries, and distinguishes itself from matching siblings by saying it should be preferred over 'chaining single-pack SEC/XBRL/news lookups' for holistic questions. This lets an agent confidently route user intents like 'research Acme' here.

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

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

The description explicitly states when to use the tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and gives trigger-phrase examples. It does not, however, contrast with potentially overlapping siblings like deep_research or compare_entities, so the comparative guidance is incomplete.

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 destructiveHint=true and readOnlyHint=false, making the destructive nature clear. The description adds no additional behavioral details beyond the annotations, such as what happens if the key does not exist.

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-loading the core action and immediately providing usage guidance. Every word is necessary, 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 simplicity of the tool (one parameter, no output schema), the description covers purpose, usage, and sibling context. It does not detail return values or error handling, but this is acceptable for a simple deletion 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 the 'key' parameter. The description adds no further meaning beyond the schema's description of 'Memory key to delete.'

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,' providing a specific verb and resource. It distinguishes from siblings like 'remember' and 'recall' by explicitly 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?

The description gives explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. 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 well-structured, starting with purpose, method, and use cases. It is moderately concise but provides essential context 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 no output schema, the description explains the output as a single text blob ready for deployment. It covers the function adequately, though it could mention potential error cases or limitations.

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

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

Schema coverage is 100% for both parameters. The description restates the url purpose but doesn't add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format (standard markdown) and distinct uses. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generation.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't state when not to use it or name alternatives, the context is sufficient for 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?

Description lists specific return fields (title, authors, abstract, AI summary, etc.), adding value beyond annotations which only indicate read-only, open-world, idempotent, and non-destructive. 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?

Single sentence with no wasted words. Front-loaded with verb and resource.

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 output schema present, the description provides a complete overview of what the tool returns. No gaps for a simple read tool with one parameter.

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

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

Single parameter 'arxiv_id' is described in both schema and description with example format. Schema coverage is 100%, so description adds minimal new meaning beyond the schema.

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

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

Description clearly specifies verb 'Get', resource 'paper', and identifier 'arXiv id'. It lists what details are included, distinguishing it from sibling tools like search_papers (which searches) and trending_papers (trending list).

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

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

Description implies use when you have an arXiv ID and want full details, but does not explicitly state when to use this tool vs alternatives (e.g., search_papers) or provide exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, signaling safe retrieval. Description adds minor behavioral details like returning 'most popular' items and a 'papers with code' view, but does not substantially expand on the safety profile.

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

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

Two sentences, no redundant words. Front-loaded with the primary action and resource. Every part 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 the simple parameter set (1 required), full annotations, and existence of an output schema, the description is nearly complete. It could explicitly mention that a list is returned, but that is implied.

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

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

Only one parameter (arxiv_id) with 100% schema description coverage. The description does not add meaning beyond what the schema already states (arXiv identifier with example). Baseline score of 3 is appropriate.

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

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

Description specifies a concrete verb ('Find') and resource ('implementations of a paper by arXiv id'), listing specific output types (GitHub repo, Hugging Face models, demo Spaces, datasets). It clearly distinguishes from sibling tools like 'get_paper' or 'search_papers' by focusing on implementations.

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 provides explicit usage contexts: 'code/implementation for <paper>', 'models trained on <paper>. It does not mention when not to use, but the purpose is distinct enough that alternatives are implied from the sibling list.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive). Description adds default behavior (active only) and output fields, enhancing transparency 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 efficient sentences: first states purpose and output, second gives usage advice. No wasted words, front-loaded with key information.

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

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

Given full schema coverage, rich annotations, and listed return fields, the description fully informs the agent about the tool's behavior and output without needing an output schema.

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

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

Only one parameter (include_inactive) with full schema coverage. Description does not add more details beyond what the schema already provides.

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

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

Clearly states it lists the caller's active subscriptions and specifies the returned fields. Differentiates from siblings like subscribe and unsubscribe by its review 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?

Explicitly advises use for reviewing monitored subscriptions before adding more or finding an ID to cancel, providing clear context for when to invoke.

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

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

Beyond the boolean annotations, the description discloses a stateful claim_token mechanism, rate limiting (5/day/identifier), that it is free and not quota-consuming, and that the team reads digests daily. It also clarifies that filing without an account returns a token for later status checks. This gives the agent a complete behavioral model despite the lack of an output 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 densely packed with unique information: purpose, use cases, exclusions, token mechanism, rate limits, and formatting guidance. It is well-structured and front-loaded with the purpose, though slightly verbose compared to the minimal style of the calibration examples. Each 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?

This is a relatively complex tool with 4 parameters, one nested object, and no output schema. The description compensates thoroughly by covering input semantics (message content, claim_token), behavioral outcomes (token retrieval, status updates), constraints (rate limit, only Pipeworx tools), and context (daily digest, free). It is complete enough for an agent to use it correctly and handle follow-ups.

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 meaningful guidance beyond the schema: it instructs not to paste the end-user's prompt into message, frames the message in terms of Pipeworx tools/packs, and explains the claim_token usage pattern (pass it back alone). This exceeds the schema's field-level documentation.

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

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

Purpose is explicit: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the verb (tell/feedback), resource (Pipeworx team), and scope (feedback about Pipeworx tools). It also distinguishes the tool from siblings like ask_pipeworx by limiting it to feedback about this connection's tools, not general questions.

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: bug, feature/data_gap, praise. It also includes strong when-not-to-use guidance: tools from other MCP servers should be reported elsewhere, with a heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary usage guidance for an AI agent deciding between this and sibling feedback/reporting 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=true, idempotentHint=true, etc. Description adds valuable context: data is derived from CF analytics-engine, no PII, cached 5min-1h. 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?

Concise paragraph with front-loaded main output, bulleted use cases, and brief notes on data sourcing and caching. 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?

No output schema, but description enumerates return fields (top tools, top packs, total call volume). Covers purpose, usage, parameter, and behavioral details adequately for a simple read-only 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 covers window parameter with enum and description (100% coverage). Description adds semantic value by contrasting short vs long windows ('hot right now' vs 'steady-state demand').

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

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

Clearly states the tool returns top tools, top packs, and call volume over a window. Distinguishes from siblings like 'discover_tools' or 'trending_papers' by focusing on AI agent call activity.

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?

Lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case). Could explicitly mention when not to use (e.g., for historical trends beyond 30d), but provides strong contextual guidance.

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

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

Adds significant detail beyond annotations: explains scanning top ~200 markets, date-axis/threshold-axis checks, partition sum validation, semantic anchor with Jaccard similarity, placeholder filtering, fill check against live CLOB depth, and conditions for not trading. 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?

Description is thorough but well-organized with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Some redundancy could be trimmed, but structure aids 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?

For a complex tool with no output schema, description provides a good mental model including output fields (opportunities[], partition_check). Missing exact return type, but adequate for agent to understand expected 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 coverage is 100% but description adds extensive context: for event parameter, explains slug format and walks child markets; for topic, explains seed question and cross-event scanning. Provides examples and behavior for each parameter.

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

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

Explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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?

Clear instructions on when to use each mode (no args for trending, event for specific market, topic for cross-event). Also mentions using polymarket_fill_risk for custom sizing. Does not explicitly compare to all siblings but provides good within-tool 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, and idempotentHint. The description adds significant behavioral detail: caching at KV level (1 hour), internal logic of model families, and a _diagnostics section to explain empty segments. 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 core purpose, but the subsequent paragraphs are verbose with detailed model formulas and internal metrics. While structured, it is longer than necessary for an agent to understand the tool, reducing conciseness.

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

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

Without an output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and edge metrics. It covers caching, filtering knobs, and reasons for empty segments, providing complete context for agent usage.

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 thorough descriptions for all 9 parameters. The tool description references parameters (e.g., knobs) but does not add substantial new meaning beyond what the schema already provides. 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx-driven signals and providing a discovery interface. The specific verb 'scan' and resource 'Polymarket markets' make the purpose unambiguous.

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

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

The description provides a usage context ('built for what should I bet on today') and explains how knobs filter opportunities, but does not explicitly contrast with sibling tools or state when not to use. It implies usage for discovery without pagination, but lacks direct guidance on 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: time-series details, first_seen, trend computation, decay rate, expired opportunities, lifecycle, and limitations (60-day TTL, daily close data). 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 fairly long but well-structured with sections (LIMITS, RESPONSE). Every sentence provides useful information, though some details could be tightened. It earns its length given 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?

No output schema exists, but the description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) and their contents, plus behavioral constraints (e.g., TTL, data gaps). Complete for the tool's purpose.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor context (e.g., 'snapshot family') but largely mirrors schema defaults and constraints. No significant value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration and trend. It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series rather than current snapshots.

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

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

The description implies usage context (e.g., differentiating between fresh and old edges) but lacks explicit when-to-use vs. alternatives or when-not-to-use guidance. It is clear enough for an agent to infer, but could contrast with polymarket_edges directly.

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 aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds valuable behavioral details: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), warns about partial basket fills converting arb into unhedged directional positions, and explains the dominant loss mode in arb-bot P&L. 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 well-organized with clear sections for modes and usage note, but it is somewhat verbose. Some details (like definitions of terms) could be tightened. However, it is front-loaded with the core purpose and remains focused on helping the agent select and use the tool correctly.

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

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

Given the complexity (two modes, 4 params, no output schema), the description is comprehensive. It explains both modes thoroughly, lists return fields (top_of_book, slippage, capture_ratio, etc.), warns about risks (thin legs, forced directional risk), and provides operational context (use before arb signals, threshold of $500). No gaps identified.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds context beyond schema: explains mutual exclusivity of 'market' and 'event', default side logic for basket mode, and clarifies size_usd meaning (max spend vs settlement notional) and clamping range (10–1,000,000). This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket), lists return fields for each, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly telling when to use this tool before those.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not always capturable, partial fills create directional risk) and contrasts with alternatives, making it clear when to use this tool versus others.

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

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

The description goes far beyond the annotations, disclosing that spreads are gross rather than net of fees, that token-overlap matching is used, that compatibility warnings may appear even with matched pairs, and that unclassified legs are never paired. It also explains the meaning of all compatibility codes and skipped counters. This is exemplary behavioral disclosure for a read-only, open-world tool.

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

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

The description is long, but every section earns its place: purpose, modes, response structure, safety fields, codes, fee disclosure, and limitations are all clearly organized and front-loaded. It reads as a dense reference rather than padding, and the warning at the end is material guidance rather than filler.

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

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

With no output schema, the description shoulders the burden of explaining return values, and it does so thoroughly: leg prices, spread points, compatibility fields, alignment data, skipped counters, and fee disclosures are all described. The edge cases and limitations—unknown temporal alignment, unclassified legs, pre-mapped not being tradeable—are explicitly covered, making the tool safely callable by an agent.

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

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

The input schema already provides 100% coverage of the three parameters, including descriptions and examples. The description adds valuable context by explaining that explicit parameters override topic-mapped sides and that both modes run the same matcher. This extra layer is useful but not strictly necessary given the schema's completeness.

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

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

The description clearly identifies the tool's function: computing cross-venue price spreads between Kalshi and Polymarket for the same resolving question. It names specific modes and expected outputs. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, leaving some differentiation to inference.

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 when to use the topic-based macro shortcuts versus explicit event ticker/slug pairing, and warns that most pre-mapped topics currently return compatibility warnings. It provides strong context for selecting the right mode, though it does not directly state when to prefer this tool over sibling 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 indicate read-only and idempotent. The description adds valuable context: scoping to identifier and effect of omitting key (list all). This goes beyond what annotations provide.

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

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

Two sentences, front-loaded with main function, followed by usage examples. No 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?

For a simple read-only lookup with one optional parameter and no output schema, the description covers purpose, usage, scoping, and sibling relationships completely.

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

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

Schema coverage is 100% with parameter description. The description reinforces that omitting key lists all, but adds minimal meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb (retrieve/list) and resource (memory). It distinguishes from siblings remember (save) and forget (delete).

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 to look up context the agent stored earlier' and provides examples of use cases. It also directs to pair with remember to save, forget to delete, giving clear when-to-use and 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 and idempotentHint, but the description adds valuable behavioral details such as the mark_read flag's effect on future calls and the returned fields. 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 concise (5 sentences), front-loaded with the main purpose, and each sentence adds value without redundancy. No unnecessary details.

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

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

With 5 parameters and no output schema, the description covers return fields and usage patterns well. However, it could briefly mention pagination or rate limits for completeness.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by providing examples (e.g., filter by type 'sec_8k') and explaining the effect of mark_read=true. This clarifies usage beyond what the schema alone provides.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from sibling tools like 'recent_changes' or 'subscribe'. It also details what the tool returns (source, citation_uri, raw event payload).

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 that polling works fine and mentions an alternative endpoint for scripts/dashboards, giving context on when to use the tool vs. direct API access. However, it does not explicitly state when not to use this tool.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: fan-out to multiple sources, fallback logic, patent soft-fail, and acceptable formats for the 'since' parameter. 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 a single paragraph that is dense but not overly long. It front-loads usage examples and then explains behavior. Could be slightly better structured with bullet points, but it is still concise and informative.

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

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

No output schema is provided, but the description compensates by detailing the return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers edge cases like fallback and soft-fail. The description is complete for a tool of this complexity.

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

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

The input schema has 100% coverage with descriptions for each parameter. The description adds extra meaning for 'since' (accepts ISO date or relative shorthand) and 'value' (ticker or CIK), going 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 explicitly states the tool provides a change feed for a company over a recent period, covering SEC filings, news, and patents. It uses specific examples like 'What's new with X' and distinguishes from the sibling tool 'entity_profile', which provides a static 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?

The description gives clear when-to-use examples and explicitly advises to use 'entity_profile' instead for static profiles. It also explains fallback behavior (GDELT to GNews) and soft-fail for patents, guiding the agent on tool selection.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds value beyond annotations: it explains scoping by identifier, persistence differences (authenticated vs. anonymous), and that it stores key-value pairs. No contradiction.

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

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

The description is concise and well-structured: first sentence states purpose, then usage guidelines, storage details, and pairing. 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 tool with 2 parameters and no output schema, the description covers purpose, usage, persistence, and pairing. It is complete and leaves no significant gaps.

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

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

Schema coverage is 100%, so the description need not repeat parameter details. It mentions 'key-value pair' and gives examples, but this adds marginal meaning beyond the schema's descriptions. 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 purpose: 'Save data the agent will need to reuse later'. It specifies the verb (save), resource (data), and context (across conversations/sessions). It also distinguishes from sibling tools like 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?

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It also advises pairing with recall and forget, offering clear direction on when to use and 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 goes far beyond the read-only/idempotent annotations by disclosing key behaviors: identifiers are labeled with source, unresolved identifiers appear under `unresolved` rather than omitted, ambiguous matches return `figi_candidates`, non-equity instruments resolve even without a ticker, ISINs map to legal entities via GLEIF, and enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable. This is rich, non-obvious behavioral context an agent needs.

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 information-dense and well-structured with an opening, supported types, and caveats, but it is extremely long and contains extended parentheticals that are hard to parse. Every sentence adds value, but the overall length and nesting hurt readability for an AI agent scanning quickly.

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

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

For a complex multi-source resolution tool with no output schema, the description covers accepted inputs, output-related edge cases (candidates, unresolved), source provenance, internal cascading behavior, and graceful degradation. An agent has enough context to call it correctly and interpret ambiguous or partial results.

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

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

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: it gives concrete examples (AAPL, 0000320193, ozempic, metformin), explains the ISIN input mapping, and provides the critical warning for bond lookups to pass the issuer name exactly as printed rather than the full noun phrase. This goes well beyond the baseline for high schema coverage.

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

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

The description opens with concrete examples and a clear statement: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It specifies the verb (resolve), the resource (entity names to identifiers), and the scope (company/drug), and distinguishes itself with "Use FIRST whenever you have a name but need an ID." This makes the tool's role unmistakable.

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

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

It explicitly states "Use FIRST whenever you have a name but need an ID," and provides detailed context on when each type applies (company vs drug) and what inputs are accepted. However, it does not explicitly name alternatives or state when NOT to use this tool (e.g., when you already have an ID and need entity_profile).

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

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

Discloses that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. Annotations already provide safety hints, so the description adds meaningful behavioral context.

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

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

Two sentences, front-loaded with the main action. No filler. 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?

Covers business context and output format (ranked list). With no output schema, description sufficiently describes return values. Could mention entity count range but schema already specifies 2-8.

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

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

Schema coverage is 100%, but the description adds value: 'First entry treated as the 'subject' for narrative' and clarifies model options ('workers-ai' default, 'anthropic' requires _apiKey).

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('compare') and resource. It distinguishes from sibling tool 'ai_visibility_check' which is for single entity checks.

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 context: 'Useful for competitive AI-marketing audits' and gives an example question. However, it does not explicitly state when not to use or list alternative tools beyond the implied contrast with ai_visibility_check.

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

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

Adds details beyond annotations: describes fan-out across services, partial failure graceful degradation, and 5-30s delay for first bundlephobia measurement.

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

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

Well-structured with front-loaded purpose, but slightly verbose; every sentence is useful.

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?

Completely covers output format, error handling, ecosystem limitations, and timing behavior, compensating for lack of 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% and the description adds no additional meaning beyond what the schema already provides for each parameter.

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

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

Clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data. Distinct from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and notes NPM-only scope with fallback 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by specifying the source (Hugging Face Papers) and the exact fields returned. 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 two sentences, front-loaded with the main purpose and return value, with no redundant information.

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

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

Given the tool's moderate complexity (2 parameters) and the presence of an output schema, the description sufficiently explains what the tool does, what it returns, and appropriate use cases. No missing critical context.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter details beyond the schema, which already describes query and limit. The description provides usage examples but not parameter semantics.

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

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

The description clearly specifies the tool searches ML/AI research papers via Hugging Face Papers, lists the returned fields (arXiv id, title, authors, upvotes, GitHub repo), and explicitly states use cases like 'papers on <topic>', differentiating it from sibling tools such as get_paper or trending_papers.

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

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

The description provides clear use cases ('Use for papers on <topic>, recent ML research about X'), offering good context for when to apply the tool. However, it does not explicitly state when not to use it or mention alternative sibling tools like deep_research or get_paper.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (truncated and flagged)', providing concrete technical behavior beyond annotations.

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

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

Three sentences: purpose, use case, technical details. Every sentence adds value. 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?

No output schema, but description explains results include character offsets and similarity scores. Also covers limitations and pairing with sibling tool. Complete for a search tool.

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

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

Schema coverage is 100%. Description adds examples for query ('supply-chain risk', 'fiscal year 2024 revenue') and clarifies that text is the document. Adds meaning 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 clearly states 'Semantic search INSIDE a fetched record' with specific verb, resource, and method. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and contrasting with simple fetch/scrape.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides workflow with sibling tool. 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?

Despite annotations already hinting at non-readOnly, non-destructive, and idempotent behavior, the description adds extensive context: account requirement, type-specific parameters, delivery constraints (SMS verification, daily cap, webhook signing), and auto-disable on failure. This goes well 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 information-dense and well-structured: purpose, account requirement, types, delivery. Every sentence adds value. It could be slightly more structured (e.g., bullet points), but it is concise given the complexity.

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

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

Despite no output schema, the description covers the return value (new subscription id) and all major aspects: types, delivery, constraints. However, it does not explicitly cover all enum options in the text and could mention the behavior for duplicate subscriptions (though idempotentHint suggests safety). Overall complete for a tool of this 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 baseline is 3. The description adds detailed examples and constraints for three of the five enum types (sec_8k, polymarket_edge, fred_series) and for delivery channels (including error handling for webhooks). However, it omits details for patent_grant and clinical_trial, which are documented in the schema. Overall, it adds significant 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 action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing solely on creation.

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

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

The description provides clear context (e.g., requires Pipeworx OAuth account, supported types) but does not explicitly state when not to use this tool or compare to alternatives. However, the purpose is unambiguous enough for an agent to select it for creating subscriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns category-bucketed examples with exact tool shapes, providing behavioral context beyond the annotations.

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

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

Somewhat lengthy but every sentence adds value. Front-loaded with trigger phrases, then explains output and usage. Could be slightly tighter but still effective.

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

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

Given the tool's role as an onboarding entry point, description covers trigger phrases, output format, usage instructions, and parameter behavior comprehensively. No output schema needed as return type is described.

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

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

Only one optional parameter 'topic' with clear schema description. Description adds value by explaining effect: 'pass topic to focus' and enumerates possible values. Schema coverage is 100%.

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

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

Clearly states it's an onboarding entry point for a new agent, lists trigger phrases, and explains it returns category-bucketed example questions with exact tool+argument shapes. Distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass topic vs no arguments.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the source (Hugging Face) and ranking method (community upvotes), which is useful but minimal. It does not disclose update frequency, cache behavior, or pagination, but given annotations, the description adequately supplements 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 two sentences: first defines the tool and source, second gives common use cases. It is front-loaded with the core action and wastes no words. 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?

Given the tool has an output schema (so return values are documented elsewhere), only two simple optional parameters, and no complex behavior, the description provides sufficient context: what the tool does, where data comes from, and when to use it. No important information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides (date and limit). The example 'limit: 15' in the schema is helpful, but the description adds no extra semantics.

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

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

The description clearly states that the tool returns today's or a given day's trending ML/AI papers ranked by community upvotes via Hugging Face Papers. It gives specific example queries that distinguish it from sibling tools like get_paper (specific paper) and search_papers (search by query). The verb 'trending' and resource 'papers' are precise.

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 provides usage scenarios (e.g., 'what are the hot AI papers', 'top papers this week'), making it clear when to use this tool. However, it does not explicitly exclude cases where other tools like search_papers or get_paper would be more appropriate, leaving a minor gap.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds value by explaining ownership enforcement and that the row is deactivated (not deleted), keeping historical events available. 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 sentences front-load the core action. Every sentence provides essential information: action, ownership, and side effect. 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 tool with one well-documented parameter, the description explains the outcome (deactivation) and the effect on history, referencing sibling 'recent_alerts'. No output schema exists, so coverage is adequate.

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

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

Schema description coverage is 100%, with the 'id' parameter already documented as 'Subscription id (uuid) returned by subscribe.' The description's mention 'by id' reinforces but does not add new meaning beyond the schema.

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

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

The description uses a specific verb 'Cancel' paired with resource 'subscription by id'. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by stating the action and ownership enforcement.

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

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

The description implies when to use (to cancel a subscription) and states ownership enforcement ('you can only cancel your own subscriptions'), which guides agent on prerequisites. It does not explicitly mention when not to use, but the context of sibling tools provides differentiation.

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

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

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations already covering safety, the description adds substantial behavioral context: it explains the two-path routing (SEC EDGAR vs. grounded pipeline), details the meaning of 'could_not_verify' vs. 'unsupported' (including the verification_error field), and notes that it replaces 4-6 sequential calls. No contradictions with annotations.

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

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

The description is long but every sentence adds value: trigger phrases, use case, routing details, verdict definitions, and error semantics. It is well-structured, front-loaded with the most actionable trigger phrases, and uses punctuation effectively to pack information. Slightly verbose but 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?

There is no output schema, so the description carries full responsibility for explaining return values. It enumerates all verdict types, mentions the actual value and citation, explains the meaning of error variants ('could_not_verify' vs. 'unsupported'), and describes the internal routing. This is exceptionally complete for a tool with two parameters and no output schema.

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

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

Schema descriptions already cover both parameters (claim and tolerance_pct) with examples and constraints (100% coverage). The description adds no direct parameter-specific information beyond the schema; it mentions percent-delta math but does not clarify tolerance_pct further, 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 tool's function: natural-language claim verification against authoritative sources, using specific trigger phrases like 'fact check' and 'verify the claim that.' It distinguishes itself from sibling tools by emphasizing the verdict output and its role in replacing multiple sequential calls, making its purpose unambiguous.

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

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

The description explicitly says to use it whenever the agent needs to check whether something a user said is factually correct, providing clear context for usage. It does not name specific alternative tools or provide when-not-to-use exclusions, but the routing explanation (company-financial vs. other claims) gives additional situational guidance.

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