Pubmed

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds key behavioral context: default model, need for _apiKey to probe Anthropic, and that the user pays Anthropic directly. No contradictions with annotations.

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

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

Three well-structured sentences: first states the core purpose, second details model options and API key, third lists returns and use cases. No wasted words; all sentences earn their place. 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?

The description covers all essential aspects: purpose, inputs (entity, models, _apiKey, context), default behavior, required conditions for Anthropic, return format (per-model score, confidence, signals, raw_response + combined view), and use cases. Given the tool's complexity (multiple models, optional key), this is comprehensive. No output schema exists, but the description adequately explains outputs.

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's added value is moderate. It reinforces the purpose of '_apiKey' ('BYO key — you pay Anthropic directly') and clarifies the 'models' parameter default. This adds useful nuance beyond the schema descriptions, justifying a score above the baseline of 3.

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

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

The description starts with a clear verb ('Probe') and resource ('LLMs'), specifies the outcome (score visibility 0-100), and gives examples of entities. It effectively distinguishes itself from siblings by focusing on probing multiple LLMs for brand/topic visibility, which is unique among 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 mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic probing. However, it does not explicitly state when not to use this tool versus alternatives like 'scan_competitor_ai_presence', nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the tool's safety and behavior are largely conveyed. The description adds value by specifying the internal routing to 3,770 tools and the return of structured answers with citation URIs, which annotations don't cover.

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

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

The description is front-loaded with the key guidance to prefer over web search, followed by detailed use cases and examples. It is comprehensive without being verbose, though slightly lengthy.

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 input schema (one parameter), rich annotations, and no output schema, the description fully explains the tool's purpose, usage, and behavioral expectations. It is sufficient for an agent to invoke correctly.

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

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

The input schema has 100% coverage with all parameters as aliases for the question. The description reinforces the natural language input and provides helpful examples, adding 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 that the tool routes factual questions to a large set of verified sources and returns structured answers with citations. It explicitly distinguishes itself from web search and lists specific domains (SEC filings, FDA data, etc.).

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 to prefer this tool over web search for factual questions and provides concrete examples of queries. It covers when to use it and contrasts with alternatives, giving clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds key behavioral details: extra LLM call, refusal reasons, and that answers are extracted solely from tool results. 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 (two sentences), front-loads the key purpose, and efficiently covers usage, behavior, and output structure without unnecessary words.

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

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

Despite no output schema, the description thoroughly explains the return format (answer, evidence, confidence, etc.) and refusal reasons, compensating well. However, it could briefly mention the lack of output schema explicitly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions aliases for the question parameter, which is already in the schema, adding no new semantics. It does not enhance understanding beyond the schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads,' specifying that it extracts answers only from tool results. It distinguishes from the sibling tool 'ask_pipeworx' by emphasizing groundedness and explicit refusal modes.

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 when answers will be quoted, cited, or acted on, and not to use for casual lookups, noting the extra cost of an LLM call over ask_pipeworx.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds extensive behavioral details: fan-out patterns, response shapes, safety short-circuits, spread warnings, resolution rule parsing. 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?

Very long and dense, but well-structured with clear sections. Could be more concise, but the organization helps an agent parse the 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?

Despite no output schema, the description comprehensively covers return shapes, edge cases, safety, and resolution rules. All needed context for agent decision-making is present.

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

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

Schema covers 100% of parameters with descriptions. The description reinforces and expands on parameter behavior (e.g., depth difference, include_raw effect), adding value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb (Research) and resource (Polymarket bet) and distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Provides explicit use cases (e.g., 'should I bet on X') and detailed fan-out examples. Does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and return of pipeworx:// citation URIs. These go beyond annotations without contradiction.

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

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

The description is packed with useful information and front-loads query examples and the key directive ('ALWAYS PREFER...'). Every sentence adds value, but it is slightly dense; a more structured layout (e.g., bullet points) could improve scanability. Still, it is efficient and earns a high score.

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

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

Given the tool has two parameters, no output schema, and no nested objects, the description covers purpose, usage, parameter details, data sources, and return format ('paired data + pipeworx:// citation URIs'). It lacks an example response snippet, but the information is sufficient for an agent to understand the tool's function and output nature.

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

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

Input schema coverage is 100%, but the description adds significant meaning: it explains that type='company' pulls specific financial metrics from the latest 10-K, while type='drug' pulls adverse-event counts and trial data. It also clarifies the values parameter with ticker examples and constraints (2-5 items). This enriches the schema's bare 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 comparisons of 2-5 companies or drugs in one parallel call, with specific query examples like 'Compare X and Y' or 'rank these companies.' It distinguishes from sequential single-pack lookups (e.g., via entity_profile) by explicitly preferring this tool for comparisons, thus differentiating from siblings.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives concrete use cases (comparing, ranking, head-to-head). It does not explicitly state when not to use, but the strong preference implies alternatives are for single-entity lookups. Could be more precise about exclusions, but the guidance 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?

The description discloses key behaviors: parallel routing to 3,770 tools, extraction of verbatim evidence with confidence and source, provision of gaps[] for unanswered facets, and a 15-60s expected duration. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description adds substantial context beyond annotations without contradiction.

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

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

The description is a single dense paragraph that front-loads the core idea. While every sentence adds value, it could be slightly more structured with bullet points for clarity. Overall it is 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?

Given no output schema, the description thoroughly explains the return format: a structured findings packet with evidence, confidence, source, fetched_at, and pipeworx:// citations, plus gaps array. It also covers behavior, usage, prerequisites, and expected timing, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds practical details: it explains that depth values quick, standard, thorough correspond to 3, 5, 8 facets respectively, and that question can be broad/multi-part. This goes beyond the schema's descriptions.

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

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

The description clearly states it performs grounded multi-source research in one call, decomposes questions into sub-questions, and routes to many tools in parallel. It also distinguishes itself from sibling ask_pipeworx by noting that the latter is for single lookups.

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

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

The description explicitly says to use this tool for broad or multi-part questions and to use ask_pipeworx for single lookups. It also mentions the requirement for a Pipeworx account and that depth:'thorough' requires a paid plan.

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=true, idempotentHint=true, destructiveHint=false, confirming safe read-only usage. The description adds that results include full input schemas with curated examples, which is beyond annotation scope and provides valuable behavioral detail.

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 efficiently packed: purpose front-loaded, usage guidance, behavioral details, and return format. Every sentence adds value with no redundancy.

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

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

Given 36 sibling tools, 6 parameters with 100% schema coverage, and no output schema, the description fully compensates by explaining what is returned (top-N tools with schemas and examples) and when to use it. It is comprehensive.

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 detailed parameter descriptions. The description adds no additional parameter meaning beyond what the schema already 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 states a specific verb-resource pair ('find tools by describing the data or task'), lists numerous example domains, and distinguishes itself from sibling tools by being a discovery/browsing tool rather than a specific data retrieval tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use, though it doesn't explicitly exclude scenarios where the user already knows the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds context on data sources (SEC, XBRL, USPTO, news, GLEIF), soft-fail on patents, and return fields, enhancing transparency without contradicting annotations.

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

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

The description is front-loaded with example queries and well-structured, but slightly verbose with details on patents sunset and LEI; could be tighter while retaining all value.

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

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

Given no output schema, the description covers return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). It does not detail formatting of fundamentals or number of news items, but overall is sufficiently complete for a profile 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%, but the description adds meaning: explains type is only 'company,' value must be ticker or CIK, and names are not supported, reinforcing the need to use resolve_entity for names.

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

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

The description starts with user-facing queries like 'Tell me about X' and explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call,' clearly distinguishing it from chaining single-source lookups.

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

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

It explicitly states 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view,' and instructs not to pass names but to use resolve_entity first, providing clear 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 destructiveHint=true and idempotentHint=true, so the agent knows it's destructive and idempotent. The description adds context about clearing sensitive data and deleting previously stored memories, but does not specify behavior for non-existent keys (though idempotency implies it may succeed silently). Overall, good transparency with minor gap.

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 extremely concise: two sentences. The first sentence states the core action, and the second provides usage guidance. No unnecessary words.

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

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

Given the tool's simplicity (one required parameter, no output schema) and the presence of annotations covering safety, the description fully covers what an agent needs: what the tool does, when to use it, and how it relates to siblings. No gaps.

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

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

Schema coverage is 100%, so the schema already documents the 'key' parameter. The description does not add any additional semantic nuance beyond the schema's description, hence the baseline score of 3.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning pairing with 'remember' and 'recall', making its purpose unambiguous.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear guidance on when to invoke the tool, and the mention of pairing with siblings suggests context regarding alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also specifies output format, which supplements the annotations.

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

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

The description is concise with two main sentences and a bullet-like list of use cases. It is front-loaded with the core action. Slightly more structured formatting could improve readability, but it is efficient.

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

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

Given no output schema, the description explains the output as 'a single text blob ready to drop at site-root/llms.txt.' It covers purpose, usage, behavior, and output adequately for a tool with two parameters and simple inputs.

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

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

Schema description coverage is 100% with both parameters ('url' and 'max_links') described. The description adds general context but does not provide new semantic detail 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 it generates an llms.txt file for any URL, with specific verb 'Generate' and resource 'llms.txt file'. It distinguishes from siblings by focusing on file generation, while related sibling tools like scan_competitor_ai_presence have different purposes.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI view. This provides clear context for when to use the tool, though it does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. Description adds behavioral detail on output format (structured vs. unstructured based on journal publication style), which is valuable context beyond the annotations. 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?

Three concise sentences: purpose, behavioral detail, and usage guidelines. Front-loaded with key info, no redundancy or 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?

Given single parameter, high schema coverage, output schema present, and clarity on when to use vs alternatives, the description fully covers what an agent needs to correctly select and invoke this 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 clear description of the 'id' parameter. Description repeats 'by ID' but adds no significant new 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?

Description uses specific verb 'get' and resource 'abstract text for one PubMed article by ID', clearly states it returns structured sections if available else unstructured, and explicitly distinguishes from siblings 'get_summary' and 'search_pubmed'.

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

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

Provides explicit when-to-use guidance ('when summarizing a single paper or answering what does paper X actually say') and gives specific alternatives for other use cases ('For batch citation metadata use get_summary; for finding papers use search_pubmed').

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds crucial behavioral context: the citation count is a floor because coverage is limited to PubMed Central and participating publishers. This informs the agent about the tool's limitations beyond the annotations, though no additional details about rate limits or return format are provided.

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 with no wasted words: a single sentence for the primary action, a sentence for use cases, a sentence for an important caveat, and a sentence for sibling distinction. It is front-loaded with the most critical 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?

Despite lacking an output schema, the description fully covers what an agent needs: the tool's purpose, input requirements, use cases, coverage limitations, and distinction from a similar tool. It is complete for a forward citation search tool with good annotations.

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

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

Schema coverage is 100% with both parameters (pmid and limit) described. The description restates that pmid is a 'single PMID' but does not add significant semantic value beyond the schema. The default limit of 10 is already in the schema. Thus, the description meets the baseline for high schema coverage.

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

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

The description explicitly states the verb 'Find papers that CITE a given article' and the resource 'forward citation search'. It specifies the input parameter (one PMID) and distinguishes itself from the sibling tool 'get_related_articles' by clarifying that it returns citing papers, not similar 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 ('who cited this', 'has this finding been replicated or challenged', tracking downstream impact) and explicitly notes when not to rely solely on this tool due to coverage limitations (PMC citation graph as a floor). It also suggests alternative tools (Semantic Scholar/OpenAlex) for full citation counts and distinguishes from 'get_related_articles'.

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, openWorldHint, idempotentHint, destructiveHint. The description adds context about using 'NIH PubMed's own computed related articles' and ranked by shared terms/MeSH/citations, which is valuable 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, front-loaded with purpose. Every sentence adds value: purpose, mechanism, use cases, and differentiation. 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?

Given the tool's simplicity (2 params, no output schema, good annotations), the description is fully complete. It explains what, how, when, and how it differs from a sibling.

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 no additional parameter semantics beyond what the schema already provides (e.g., pmid and limit 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 'Find papers SIMILAR to a given article' and explains the mechanism (pubmed_pubmed neighbors). It distinguishes itself from get_citations, making 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?

Explicitly lists use cases: 'more papers like this', building a reading list, broadening literature search. Also contrasts with get_citations for when not to use, providing clear 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, idempotentHint, non-destructive. Description adds useful context: batch limit (~200 IDs), input format (comma-separated), and cost efficiency hint. 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, no wasted words. Purpose first, then usage guidance and alternative. Perfectly front-loaded.

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

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

With an output schema present (not shown but indicated), description covers input format, batching, and alternatives. For a simple ID-to-metadata tool, this is fully 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 already describes the 'ids' parameter with 100% coverage. Description adds meaningful constraints: batch limit and that it's a comma-separated string, which goes beyond schema description.

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

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

Description clearly states the tool resolves PubMed IDs to citation metadata (title, authors, journal, date, DOI). It explicitly distinguishes from siblings by mentioning search_pubmed (which produces IDs) and get_abstract (for abstracts).

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?

Gives explicit when-to-use (when you have PMIDs and need citation) and when-not-to-use (use get_abstract instead for abstracts). Also provides batching advice to be more efficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which describe safety and idempotency. The description adds return fields and mentions the include_inactive parameter, but does not significantly extend beyond annotations. Adequate given annotation coverage.

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

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

Two concise sentences, front-loaded with action and return fields, followed by usage guidance. 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 list tool with no output schema, the description enumerates return fields and provides usage intent. Completeness is high given the tool's simplicity and rich annotations.

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

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

Schema covers 100% of parameters with descriptions. The description implicitly refers to the 'include_inactive' parameter by mentioning active subscriptions, but does not add substantial meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

Clearly states the tool lists the caller's active subscriptions and enumerates return fields. Differentiates from related tools like subscribe and unsubscribe.

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

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

Explicitly advises using it to review monitored subscriptions before adding more or to find an id to cancel, providing clear usage context. No explicit when-not-to, but adequately covers common use cases.

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

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

The description discloses key behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. Annotations are all false, which is consistent with a feedback 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 concise (4 sentences), front-loaded with purpose, then conditions, then instructions, then notes. Every sentence adds value with no redundancy.

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

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

Despite having no output schema, the description covers all necessary aspects: purpose, when to use, what to include, constraints (rate limit, quota), and impact (roadmap). Complete for a simple feedback 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% and the schema itself has good descriptions for each parameter. The description adds value by contextualizing the 'type' parameter and explaining how to write the message, but it does not significantly extend schema meaning.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb 'tell' and the resource 'Pipeworx team', and distinguishes from sibling tools which are about research, queries, etc.

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

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

The description provides explicit when-to-use guidance: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises on what to describe and what to avoid ('don't paste the end-user's prompt').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h, and the aggregation nature. No contradictions.

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

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

The description is concise: two sentences plus a bullet list. It front-loads the purpose and then delivers use cases. Every sentence adds value with no redundancy or fluff.

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

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

With no output schema, the description explains what is returned (top tools, packs, volume). It covers parameter, behavior (caching), data source, and privacy. For a simple tool with one optional parameter, this is fully complete.

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

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

Schema has 100% coverage with description for the 'window' parameter. The tool description adds semantic guidance (shorter windows for hot, longer for steady-state) beyond the schema's enum description. This is helpful but not extensive.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) for a window. It uses specific verbs and resource names, and the listed use cases differentiate it from sibling tools like 'discover_tools' or 'entity_profile'.

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

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

Three explicit use cases are provided, indicating when this tool is valuable (e.g., discovering hot data sources, confirming canonical choices). It lacks explicit 'when not to use' or direct alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint = true, destructiveHint = false. Description adds depth: monotonicity violation checks, partition-sum checks, semantic anchor with Jaccard similarity, partition filter for placeholders, and fill check against live CLOB depth. 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-organized and front-loaded with the most critical info (requirement and mode selection). It covers all necessary details without redundancy, though it is somewhat lengthy due to the complexity. 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's complexity (two modes, multiple checks, fill validation), the description is highly complete. It explains the response format (opportunities[] with fields, partition_check) and edge cases like skipped_low_similarity and placeholder fraction >20%. No output schema exists, so the description fully covers return values.

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%, but the description adds significant value beyond the schema: provides slug examples, explains mode behavior, and details the checks performed. This helps the agent understand the implications of each parameter choice.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing between event (single-event) and topic (cross-event) modes. The name and title align perfectly, and it differentiates from sibling tools 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?

Explicitly requires one of event or topic, with detailed guidance on when to use each mode. Provides examples of slugs and seed questions, and explains that cross-event mode catches patterns missed by single-event. Clearly states that calling with no args fails.

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

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

The description discloses many non-obvious behaviors: caching (1h), model families, response structure (by_segment), placeholder filters, Fed bets exclusion, diagnostic counters, and tradeable-edge knobs. It adds significant context beyond annotations which already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive.

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 extremely verbose and dense, running multiple paragraphs with detailed model family descriptions and edge calculation formulas. While informative, it lacks conciseness and would benefit from structured bullet points or shorter sentences.

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

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

Given the tool's complexity (9 parameters, multiple model families, no output schema), the description is highly complete. It explains the response format, diagnostics, caching, filtering thresholds, and even the mathematical rationale behind certain filters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly vs min_kelly) and providing usage examples for knobs like slippage_pp and category_filter.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It positions itself as a discovery tool for betting opportunities, distinguishing it from siblings like polymarket_arbitrage.

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

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

The description provides extensive usage context, including when to use it ('what should I bet on today'), tradeable-edge knobs, and caching behavior. However, it does not explicitly state when not to use it versus specific sibling tools, though the sibling list implies alternatives.

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

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

The description adds significant behavioral context beyond annotations: explains response structure, how snapshots are written, gaps, and decay computation. All annotations (readOnly, idempotent, etc.) are consistent and reinforced.

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 detailed but efficiently structured, starting with the core purpose and following with response format and limits. While it could be slightly more concise, 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?

Despite no output schema, the description thoroughly details the expected response (tracked[], expired[], snapshot_dates[]), covers edge cases (gaps, history bounds), and explains behavior (decay from daily closes). Completeness is excellent 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% with descriptions for both parameters. The description adds meaning by explaining 'days' as lookback (default 14, max 30) and 'window' as snapshot family with examples, providing context beyond the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides clear context for when to use the tool (to differentiate between fresh and old edges) and includes limits (60-day TTL, snapshot start). However, it does not explicitly say when not to use it or mention specific alternatives beyond the implied 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?

Goes far beyond annotations by detailing the check process (walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, verdict) and highlighting risks (thin books, partial fill directional risk). No contradiction with annotations (readOnlyHint: true matches the read-only check nature).

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

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

The description is relatively long but well-structured with clear section headers (SINGLE-MARKET, BASKET) and a concluding usage note. Every sentence adds necessary detail for a complex multi-mode tool; however, a slightly more compact presentation could improve skimmability.

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

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

For a tool with no output schema, the description thoroughly enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers all parameter nuances, mode behaviors, and risk warnings. Fully addresses the complexity of fill-risk analysis on order books.

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 significant value: explains mode selection (market vs event), clarifies side default behavior in basket mode (auto from partition sum), and expands on size_usd meaning (spend vs target proceeds for single-market; settlement notional for basket). This far exceeds schema documentation alone.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It directly ties to sibling tools by advising use before acting on polynarket_arbitrage or polynarket_edges signals, providing clear differentiation.

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

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

Explicitly states when to use ('before acting on any polynarket_arbitrage SELL/BUY-EVERY-LEG signal or any polynarket_edges trade above ~$500') and warns against misuse (theoretical overround on thin books is not capturable, partial basket fills convert arbs into unhedged positions). Provides clear context for decision-making.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructibleHint false. The description goes far beyond annotations by detailing two modes, explaining safety fields (compatibility_warning with two cases), temporal_alignment, skipped leg counters, and the fact that pre-mapped topics often yield warnings. It discloses exactly what the tool does in various edge cases, exceeding the typical transparency level.

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: it starts with overall purpose, explains modes, response fields, and safety caveats in a logical order. Every sentence adds value, but the description is relatively long (approximately 200 words). Given the complexity of the tool, this length is justified, and there is no fluff, so it earns a 4.

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

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

The tool has 3 parameters, no output schema, and relatively complex behavior. The description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields), edge cases (compatibility_warning conditions, temporal alignment), and limitations (pre-mapped topics often not tradeable). It also includes counters for skipped comparisons. For a read-only, open-world tool, this level of detail ensures an agent can correctly interpret results and understand when the tool provides meaningful output.

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

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

Schema description coverage is 100%, so schema already documents all three parameters. The description adds context by explaining the two modes (topic vs explicit tickers) and listing the pre-mapped topic values, but it doesn't add new semantic meaning beyond what's in the schema. It reinforces the usage pattern but doesn't compensate for any gaps, so a 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 it provides cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the resource (spread) and action (compute), and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and explicitly mentioning two modes.

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

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

The description gives explicit guidance on when to use the tool: to compare same-outcome prices across venues. It warns that most pre-mapped topics return compatibility_warning, so real spreads are rare, which helps set expectations. However, it doesn't explicitly say when to avoid this tool in favor of siblings like polymarket_arbitrage, though the pre-mapped topics and caution about equivalence serve as implied 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 indicate read-only, idempotent, non-destructive. Description adds value by explaining scope (anonymous IP, key hash, account ID) and the dual behavior when key is omitted (list all keys). No contradictions.

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

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

Three well-structured sentences. First sentence covers core function and dual behavior. Second provides usage context. Third covers scope and pairing. Efficient and front-loaded, though could be slightly more terse.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it does, when to use, and scope. It pairs with remember/forget. Lacks explicit return format but inferable. Complete enough given simplicity.

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

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

Schema has one optional parameter 'key' with description. The description repeats and adds context: omitting key lists all keys. Since schema coverage is 100%, description adds meaningful use-case context beyond schema.

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

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

Description clearly states it retrieves a value saved via remember or lists all keys when key omitted. Verb 'retrieve' and specific resource 'value previously saved' make purpose unambiguous. Distinguishes from sibling tools 'remember' and 'forget' by naming them directly.

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 context: 'look up context the agent stored earlier' and mentions scope by identifier. Does not explicitly state when NOT to use, but the pairing with remember/forget implies alternatives. Could be stronger with exclusion cases, but adequate.

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

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

The description discloses that setting mark_read:true flags events as read, which is a state change. However, annotations include readOnlyHint=true, implying no state modification. This contradiction between description and annotation lowers transparency, as the rubric penalizes such contradictions.

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

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

The description is concise at 3-4 sentences, front-loaded with the main action, and each sentence contributes meaningful information. 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 tool with 5 parameters and no output schema, the description adequately covers behavior, parameters, and return composition. It provides enough context for correct invocation without 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 covers 100% of parameter descriptions, and the description adds substantial value: it gives an example filter (sec_8k), clarifies 'since' expects an ISO timestamp, and explains the effect of mark_read. This goes beyond schema details.

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

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

The description clearly states it pulls fired events from a subscription feed, specifies the resource (alerts), and details returned fields (source, citation_uri, payload). It is specific and unambiguous, fully distinguishing the tool's purpose without needing explicit sibling differentiation.

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

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

The description provides usage context including that polls work fine and mentions an alternative access method (GET URL for scripts/dashboards). It explains mark_read behavior but does not explicitly state when not to use this tool versus siblings, leaving some room for improvement.

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 readOnly, idempotent, not destructive. Description adds details: fans out to multiple sources, fallback logic (GDELT→GNews), USPTO sunset soft-fail, parameter format (ISO or relative), and return structure with citations.

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

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

Single paragraph efficiently front-loads purpose and usage, then details sources, parameters, and alternatives. No wasted sentences; every sentence adds 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 complexity (multi-source, no output schema), description adequately explains return format (changes grouped by source, count, citations). Covers required parameters and sibling differentiation. Minor lack of edge-case handling (e.g., no data) but sufficient.

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

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

Schema coverage is 100% with descriptions. Description adds value by detailing `since` format (ISO or relative, examples like '7d', '1y'), and clarifies `value` can be ticker or CIK. 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 provides a change feed for a company in recent days/weeks/months via one parallel call, listing specific sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool entity_profile by specifying use case boundaries.

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

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

Explicit guidance is given: 'Use entity_profile instead when you want the static profile regardless of window.' Also provides example queries like 'What's new with X' indicating when to use.

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

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

Annotations provide idempotentHint=true, etc. Description adds key-value scoping, identifier scoping, and persistence details (authenticated vs anonymous) 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?

Five sentences, front-loaded with main purpose, each sentence adding new information without redundancy. Efficient and clear.

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 (2 params, no output schema), the description covers purpose, usage, persistence, and pairing. Complete for the tool's complexity.

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

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

Schema coverage is 100% with key and value descriptions. Description adds examples (e.g., 'subject_property', 'target_ticker') and clarifies usage context, adding value beyond schema.

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

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

The description states 'Save data the agent will need to reuse later' with specific verb and resource. It clearly distinguishes from siblings 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?

Explicitly says 'Use when you discover something worth carrying forward' and notes pairing with recall and forget. Lacks explicit when-not-to-use but context is sufficient.

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

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

Annotations already declare read-only and idempotent. Description adds internal cascading behavior and replaces manual lookups, plus details on returned fields like ticker, CIK, RxCUI, and citation URIs.

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

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

Efficiently structured: starts with example queries, states purpose, then details types. All sentences contribute substantive information with no redundancy.

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

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

Covers both entity types with return details. No output schema but description explains what to expect. Adequate for a simple lookup tool with clear use case.

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 description enriches the schema: explains accepted input variants (ticker, CIK, name for company; brand or generic for drug) and what each returns. Schema coverage is 100%, and description adds value beyond.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples for company and drug types. It is distinct from sibling tools as none serve this resolver function.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' Describes input formats per type. No explicit when-not-to-use, but usage context is clear.

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

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

Annotations already indicate safe read-only operations. The description adds that it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations without contradiction.

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

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

Three concise sentences front-loaded with purpose. 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?

Given four parameters, no output schema, and safe annotations, the description covers purpose, usage, and return format. It lacks details on error handling or rate limits but is sufficient for this read-only comparative 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% and descriptions are adequate. The description adds minor value by noting the first entity is treated as the subject for narrative, but otherwise does not add meaning beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side. It uses specific verbs like 'probes', 'ranks', 'surfaces', and distinguishes from sibling tools like ai_visibility_check by aggregating results into a ranked list.

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits and gives an example question. It implies when to use this vs ai_visibility_check (single entity vs multiple), but does not explicitly state when not to use or list alternative sibling tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses key behaviors: it fans out to external services, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30 seconds. 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 a single paragraph that front-loads the main purpose and provides comprehensive details. It is somewhat long but every sentence adds value. A more structured format (e.g., bullet points for return fields) could improve readability, but it is concise enough.

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?

Since there is no output schema, the description fully explains return values: summary block fields, per-advisory details, links, and alternative versions. It also covers error handling with partial failures and sources_failed. The tool's behavior is fully documented.

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 both parameters. The description adds minor value by mentioning scoped packages are accepted and version defaults to latest, but these are already implied by the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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 specific purpose: a composite check for npm packages using deps.dev and bundlephobia to answer safety, popularity, and size questions. It distinguishes itself from sibling tools, which are either unrelated or for other ecosystems.

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

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

The description explicitly tells when to use the tool: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. It also provides a clear exclusion: NPM ecosystem only in v1, and directs to deps.dev:version 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 declare readOnlyHint, idempotentHint, etc. Description adds useful behavioral context: returns PubMed IDs, supports field qualifiers, and that IDs can be resolved by other tools. 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?

Approximately 70 words, front-loaded with the key point, no wasted sentences. Efficient yet 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?

Given the output schema exists, the description does not need to detail return values. It covers overall purpose, usage, scope, source authority, and how it integrates with sibling tools, making it fully complete for this 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%, but description adds value by explaining the query parameter supports keywords, authors, and MeSH terms with field qualifiers, and provides examples. This enhances understanding beyond the schema.

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

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

The description clearly states the tool searches PubMed for biomedical research, using specific verbs like 'Searches'. It distinguishes itself from siblings (get_summary, get_abstract) by noting it returns PubMed IDs that those tools resolve.

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 'PREFER OVER WEB SEARCH' for biomedical topics, and lists concrete use cases like 'papers on X', 'what does the literature say about Y'. This provides clear guidance on when to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds implementation details (BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag) that go beyond the annotations and help the agent understand what to expect.

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

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

The description is a single dense paragraph that efficiently packs purpose, usage, behavior, and implementation details. It could be slightly more structured (e.g., bullet points), but it is not verbose and 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?

For a tool with no output schema, the description describes the return format (passages with character offsets and similarity scores) and operational constraints (200K char cap, truncation). This is sufficient for the agent to understand the tool's role and output.

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

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

Schema coverage is 100% with all parameters described. The description reinforces the meaning of 'text' and 'query' with examples but does not add significant new information 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 it performs semantic search inside a previously fetched record (e.g., SEC 10-K, article). It specifies output (top-N passages with offsets and scores) and distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Also mentions the alternative (ask_pipeworx_grounded) and how they pair together, giving clear context for agent decision-making.

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

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

The description provides extensive behavioral details beyond the annotations: it returns a new subscription ID, requires a specific account type, explains supported types with examples, and details delivery channel constraints (e.g., SMS cap, webhook auto-disable, HMAC signing). No contradiction with 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?

The description is fairly concise and front-loaded with the main purpose, but it includes a lot of inline examples and constraints that make it slightly verbose. A bulleted list could improve readability, though it remains efficient for the information conveyed.

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

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

For a tool with 3 parameters, nested objects, no output schema, and complex behavior (multiple types, delivery channels, account requirements), the description is remarkably complete. It covers return values, prerequisites, type-specific parameters, and delivery channel failure modes, leaving little ambiguity.

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

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

The description adds significant meaning beyond the input schema: it explains the enum values for 'type' with context (e.g., sec_8k matches ticker and item codes), gives concrete examples for 'params' and 'delivery', and specifies constraints like phone verification and rate limits. Schema coverage is 100% but the description enriches 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 that the tool creates a proactive monitoring subscription to a live-data event stream, using the specific verb 'Create' and identifying the resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing 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 explicitly states when to use the tool: for creating subscriptions to live-data event streams, and notes that a Pipeworx OAuth account is required, suggesting that anonymous/BYO accounts are not suitable. However, it does not explicitly mention alternative tools for viewing or managing subscriptions, though siblings provide that context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the output structure (category-bucketed example questions with tool+argument shapes) and the default behavior (full spread without arguments). 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 relatively lengthy but front-loads the key purpose and includes necessary details about usage and output. Every sentence adds value, though some repetition of categories could be trimmed. Overall well-structured for quick scanning.

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

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

Given that the tool has no output schema and 100% schema coverage for the single parameter, the description adequately explains the return format (category-bucketed examples) and usage. It is complete for an onboarding/discovery tool, though it could mention that no arguments return full spread and that the examples are live.

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 provides a description for the single optional 'topic' parameter. The description adds meaning by listing possible values (finance, pharma, etc.) and explaining that omitting it gives a cross-category spread, going beyond the schema's description.

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

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

The description clearly states the tool's purpose as the onboarding entry point for learning what Pipeworx can do. It lists specific types of examples returned (company financials, drugs, etc.) and distinguishes itself as the first tool to use when the agent doesn't know what Pipeworx can do, differentiating it from siblings.

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

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

The description explicitly advises using this tool first when the agent doesn't know Pipeworx's capabilities. It explains the output (category-bucketed example questions) and notes the optional topic parameter for focus. While it doesn't explicitly state when not to use it, the context is clear and actionable.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds that the row is deactivated not deleted, and historical events stay available via recent_alerts. 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?

Two sentences, no wasted words. First sentence states the action, second covers ownership and behavioral details. Perfectly concise.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, usage constraints, and behavioral side effects (deactivation, event retention). Complete.

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

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

The single parameter 'id' is fully described in the schema ('Subscription id (uuid) returned by subscribe'). The description does not add additional semantic information beyond stating 'by id'.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription', and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 ownership is enforced and you can only cancel your own subscriptions, providing clear context for when to use. It does not explicitly mention alternatives but the sibling list provides that implicitly.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return format (verdict types, structured form, citation, percent delta) and notes that it replaces multiple sequential calls. 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 well-structured with a clear purpose, usage examples, scope, and return details. It is front-loaded with natural-language query patterns. While lengthy, it remains focused and informative without redundancy.

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

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

For a single-parameter tool with high schema coverage and comprehensive annotations, the description fully explains the tool's input, output, domain, and value. It describes return types and citations, making it self-contained despite the lack of 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?

Schema coverage is 100%, so baseline is 3. The description provides examples of valid claim inputs, adding marginal value beyond the schema description. No additional parameter details like formatting constraints are given.

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 performs natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides examples of input phrasing and specifies the domain (SEC EDGAR + XBRL). However, it does not explicitly differentiate from sibling tools like deep_research or ask_pipeworx_grounded that might also handle fact-checking.

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

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

The description says to use it 'whenever the agent needs to check whether something a user said is factually correct,' but then limits to company-financial claims. It does not mention when not to use the tool or suggest alternative tools for claims outside its scope, leaving usage guidance incomplete.

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