Pubmed

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

Though annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context: the default workers-ai model is free, and using Anthropic requires a BYO API key with the caveat 'you pay Anthropic directly for those calls.' This discloses authentication and cost behavior beyond what annotations provide, with no contradiction.

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

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

The description is four sentences long, front-loaded with the core purpose, and every sentence adds distinct information (action, defaults/cost, return format, use cases). No filler or redundancy.

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

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

Despite lacking an output schema, the description specifies the per-model return shape ({score, confidence, signals, raw_response}) and the combined view. Combined with the complete input schema and annotations, the agent has sufficient information to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning for `_apiKey` by noting the cost implication and for `models` by clarifying the default behavior. Other parameter semantics are already well covered in the schema, so the incremental value is moderate.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly defines the tool's function and differentiates it from sibling tools that focus on asking specific platforms (e.g., ask_pipeworx) or competitor scanning, by emphasizing multi-LLM visibility scoring.

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

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

The description explicitly states three use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and distinguishes between free and paid model options. However, it does not name alternative tools or provide explicit 'when not to use' guidance, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds value with details like routing to 5,564 tools, returning stable citation URIs, and being a fast default entry point. No contradiction; the extra context is useful.

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

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

The description is longer than typical but every sentence earns its place, providing usage rules, examples, and alternatives. It's front-loaded with the most critical guidance. Slightly verbose but well-structured with clear sections.

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

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

Given the complexity and lack of output schema, the description covers purpose, usage, alternatives, and expected output (structured answers with citations). It's comprehensive for a tool with simple parameters and strong annotations, leaving few gaps.

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

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

Schema has 6 parameters all being aliases for 'question', with descriptions fully covering them ('Alias for question'). Since schema description coverage is 100%, baseline is 3. The description doesn't add new parameter semantics beyond noting natural language input, but that's sufficient.

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

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

The description clearly states the tool routes factual questions to authoritative data sources and returns structured answers with citations. It explicitly lists data domains (SEC filings, FDA, FRED, etc.) and distinguishes from siblings like ask_pipeworx_grounded and deep_research by explaining when to step up.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH' for specific categories, 'START HERE for most questions', and gives alternatives when to use grounded or deep_research. Includes concrete examples and trigger phrases, making when-to-use unambiguous.

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 non-destructive, but the description adds valuable behavioral context: it is a live experimental router with candidate routing improvements, currently no candidate active, and it is a full working router rather than a fallback. It also clarifies that the response shape is identical to ask_pipeworx, which is useful given the absence of an output schema.

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

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

The description is three sentences, front-loaded with the core identity and usage. Some redundancy exists ('identical router' vs 'matches ask_pipeworx exactly'), but each sentence provides useful context about the beta nature, current state, and practical use. It is concise and well-structured for quick agent parsing.

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

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

Given the tool's complexity as a universal router with no output schema, the description covers purpose, usage, behavioral state, and points to the shared response shape. It could add rate-limit or error details, but for an experimental variant of a known tool, this is sufficiently complete.

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

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

Schema description coverage is 100%: all 6 parameters are documented as aliases for 'question'. The description adds no additional parameter semantics beyond stating the tool accepts the same arguments as ask_pipeworx, so it relies fully on the schema's existing documentation. 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 identifies the tool as 'Beta version of ask_pipeworx: identical universal router' with the same 5,564 tools, arguments, and response shape. It distinguishes it from siblings (ask_pipeworx, ask_pipeworx_grounded) by labeling it the experimental edge, and uses a specific verb ('ask') with a clear resource (universal router).

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 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use criterion. It also explains the current state (no active candidate, matches stable router) and the comparison against the stable router, effectively guiding an agent to choose this tool for experimental routing.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich context: it discloses the exact return structure (answer, evidence, confidence, etc.), lists all refusal reasons, and notes the extra LLM call. It also emphasizes that only tool-result content is used, preventing hallucination expectations. No contradiction with annotations.

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

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

The description is dense but well-structured: it front-loads the core value proposition, then explains the mechanism, return format, and usage guidance. Every sentence adds substantial information, and there is no redundant filler. It is sufficiently concise for the complexity it describes.

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 (routing, extraction, refusal handling) and the lack of an output schema, the description compensates fully by documenting the exact response shape and all possible refusal reasons. It also covers cost trade-offs and use cases, making it complete for an agent to invoke correctly.

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

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

The input schema covers all 6 parameters with 100% coverage, including the primary 'question' parameter with aliases. The description does not add any parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' with a specific mechanism: routing like ask_pipeworx but extracting answers solely from tool results. It distinguishes itself from siblings by mentioning the extra LLM call and the refusal behavior, 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra cost. This gives the agent actionable decision 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?

The description goes far beyond the readOnlyHint/idempotentHint annotations, detailing resolver contracts (market_match_confidence, market_match_score), edge-case handling (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), fan-out behavior, and even cancellation-rule parsing. It also discloses safety mechanisms and potential data-fetch fallbacks, providing extensive behavioral context.

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

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

The description is lengthy but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The core purpose is front-loaded in the first sentence. While long, each section adds essential behavioral detail for a complex tool, earning its place, though some redundancy exists (e.g., closed/dead market paths).

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 thoroughly explains return shapes: result.market fields, result.analysis with model probabilities, result.evidence keyed by source, and the resolver contract (market_match_score, alternatives, suggestions). It also covers status codes, safety suppression, and cancellation-rule risk, making it complete for an agent to invoke and interpret responses.

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 100% coverage of all three parameters with clear descriptions and defaults. The description mainly restates parameter formats and adds context about fan-out and response, but does not meaningfully augment the parameter semantics beyond what the schema already offers. 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states what the tool does and distinguishes it from siblings like polymarket_arbitrage and deep_research by focusing on one-call bet research with Pipeworx data.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear usage context. However, it does not explicitly mention alternatives or exclusions (e.g., 'not for validating historical claims'), so it stops short of a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description explains data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data plus citation URIs. This rich behavioral context is not provided by the annotations and significantly aids the agent in understanding the tool's side effects and output.

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

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

The description is front-loaded with the most critical purpose (side-by-side comparison in one call) and then efficiently packs details on data sources, sorting, and return format. Every sentence contributes essential context, with no fluff or repetition.

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

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

Given the tool has no output schema, the description compensates by stating it returns paired data and citation URIs. It covers key behavioral aspects for both entity types, addresses fiscal year handling, and notes that it replaces many sequential lookups. This makes the description sufficient for an agent to understand what the tool does and what to expect from it.

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?

Although the schema already describes the parameters, the tool description adds substantial meaning: it explains what type='company' vs 'drug' retrieve and gives concrete examples (tickers like AAPL, MSFT; drug names like ozempic, mounjaro) for the values array. This goes well beyond the schema's basic descriptions, fully compensating for any residual ambiguity.

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. It provides example queries and explicitly distinguishes itself from sequential single-entity lookups, making its purpose and scope unmistakable.

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

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

The description gives explicit when-to-use guidance ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'), lists trigger phrases like 'X vs Y' and 'which is bigger', and details the type-specific behavior for 'company' and 'drug'. It effectively communicates when this tool is the right choice over 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?

Even though annotations already signal read-only/idempotent/destructive false, the description adds substantial behavioral context: latency expectations (15-60s, up to ~90s), paid requirements, gap-recovery/second-hop behavior, explicit gaps[] for unanswered facets, contradictions[] flags, path semantics, and the guarantee that 'never invent' data. This is far beyond what the annotations convey.

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

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

The description is long but every sentence earns its place: it covers prerequisites, scope, comparisons, transactional expectations, output shape, limitations, timeout behavior, and depth semantics with no fluff or repetition. It is front-loaded with the most operationally critical caveat (an account requirement), then moves in a logical sequence.

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

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

This is a complex orchestration tool with no output-schema eviction of return-value needs; the description pays the full burden by explaining the packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), the use of gaps[], contradictions[], hop field, encountered-excerpt behavior, and approximate latency. All key behaviors that an agent would need to form expectations and able to invoke the tool correctly are 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-description coverage is 100%, so the baseline is 3. The description adds meaningful nuance: depth value costs poll, depth:thorough requires paid plan, and it explains what 'standard' (re-angles unanswered facets) and 'thorough' (chases the best leads) actually do. The description also clarifies that the question parameter can be broad or multi-part, which classicizes the schema's plain 'natural language' label.

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

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

The description names a specific action ('Grounded multi-source research'), specifies the resource ('Pipeworx's 1462 STRUCTURED data sources'), and clearly separates it from open-web search ('this is NOT open-web search'). It also distinguishes itself from key siblings like ask_pipeworx and notes what it returns (findings packet, gaps[], citations), making its identity unmistakable.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also prefaces with an account requirement and says to use ask_pipeworx, a free tier alternative, when not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations by explaining the return structure: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This is useful and non-contradictory.

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 with a clear front-loaded purpose. The domain list is long but relevant and earns its place by showing the scope. No redundant repetition of schema details. Slightly verbose due to the list, but appropriate for a discovery tool.

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

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

No output schema exists, but the description compensates by explaining what the tool returns (top-N tools with names, descriptions, full input schemas, examples, ready to call). It also gives strategic guidance ('Call this FIRST'). It doesn't cover limits or edge cases, but those are in the parameter schema, so the description is sufficiently complete for the tool's purpose.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by enumerating the domains the query can describe (SEC filings, financials, FDA drugs, etc.), giving the agent concrete examples of what to put in the 'query' parameter. This goes beyond the schema's generic 'Natural language 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 starts with 'Find tools by describing the data or task', which clearly states the action (find/discover) and the resource (tools). It distinguishes this from sibling tools by explicitly positioning it as the discovery mechanism and listing the domains it covers. This is a specific, actionable purpose.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It doesn't name specific alternatives or provide a when-not-to-use, but the guidance is clear and strong for a meta-tool.

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

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

Discloses fan-out across sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), the patent API sunset and soft-fail behavior, and the GDELT→GNews fallback. These behavioral details go well beyond the annotations (read-only, idempotent) and help the agent anticipate failure modes and data caveats.

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

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

The description is dense but contains some redundancy with the parameter schema. It is front-loaded with examples and core purpose, then details fan-out and return fields. Each sentence adds value, though it could be slightly tighter by reducing the repeated parameter constraint.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is remarkably complete. It lists the return fields, failure modes, fallback behavior, input constraints, and a prerequisite (resolve_entity). This makes it self-sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the description's parameter guidance (e.g., "Pass ticker "AAPL" or zero-padded CIK "0000320193"") largely duplicates what the schema already states in the 'value' property description. It adds little new semantic meaning beyond the schema's own examples.

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

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

The description opens with concrete user phrases ("Tell me about X", "research Acme") and states the core function explicitly: "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes itself by emphasizing the holistic single-entity profile compared to sibling tools like compare_entities or deep_research.

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

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

Provides explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also gives a clear exclusion and alternative: "names not supported (use resolve_entity first if you only have a name)."

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 description's 'delete' aligns with those. It adds the context of clearing sensitive data, which gives a rationale for the destructive action, but does not disclose additional behavioral details like what happens if the key does not exist or whether deletion is reversible.

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

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

The description is two sentences that front-load the core action ('Delete a previously stored memory by key') and then provides usage context. Every word earns its place, 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?

For a simple one-parameter tool with comprehensive annotations (destructive, idempotent) and no output schema, the description covers purpose, usage timing, and relationships to sibling tools. It is 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?

The schema already describes the parameter as 'Memory key to delete' with 100% coverage. The description adds only 'by key' and 'previously stored memory,' which does not significantly enhance the schema's meaning. Baseline 3 is appropriate because 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 function: 'Delete a previously stored memory by key.' This uses a specific verb (delete) and resource (memory), and explicitly distinguishes it from the sibling tools 'remember' and 'recall' by positioning it as the deletion counterpart.

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

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

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember and recall,' giving clear contextual guidance without needing to explicitly exclude 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the process: fetches the page, extracts title/description/key links, emits standard llms.txt markdown, and returns a single text blob. This provides useful behavioral context without contradicting 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 compact and well-organized: first sentence states the core action, second explains the internal steps, third describes output, and final sentence lists use cases. Every sentence earns its place with no filler or redundancy.

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

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

With no output schema, the description clarifies that the return is a text blob. It explains inputs (URL, optional max_links via schema), process, and output. It does not detail failure modes or limits (e.g., fetch timeouts), but given the simple nature and strong annotations, it is sufficiently complete for an agent to select and invoke correctly.

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

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

The schema already describes both parameters (url and max_links) with 100% coverage. The description adds no new parameter-level detail, but it does mention 'title/description/key links' which aligns with what the tool extracts, indirectly supporting the url parameter. The baseline of 3 applies because schema handles semantics fully.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the purpose (helping AI crawlers index a site) and distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which serve as clear when-to-use guidance. It does not mention when NOT to use or name alternatives, but the use cases cover typical scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by explaining that the abstract may be returned with structured sections (background, methods, results, conclusions) or unstructured, depending on the journal. This goes beyond what annotations provide, though it does not mention rate limits or authentication.

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

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

The description is concise and well-structured: it starts with the core function, then explains the structured/unstructured behavior, then gives usage guidance and alternatives. Every sentence serves a purpose and there is no fluff.

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

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

Given that the tool has a simple input schema (two synonym parameters), rich annotations, and an output schema, the description covers all essential aspects: what it returns, the variability of the return format, and when to use it relative to siblings. It is complete for this 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?

The input schema covers both parameters (id and pmid) with descriptions and notes that pmid is a synonym for id. The description adds only that it is 'by ID', which is already implied by the schema. With 100% schema coverage, the baseline of 3 is appropriate; the description does not add deeper semantic 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 returns the full abstract text for one PubMed article by ID. It also explicitly distinguishes itself from sibling tools by naming get_summary for batch citation metadata and search_pubmed for finding papers, so the purpose is unambiguous.

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

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

The description provides explicit usage guidance: 'Use when summarizing a single paper or answering what does paper X actually say'. It also explicitly states alternatives: 'For batch citation metadata use get_summary; for finding papers use search_pubmed', giving clear when-to-use vs. 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?

Even though readOnlyHint and openWorldHint are present, the description adds crucial context: it explains the PMC citation graph coverage limitation, that counts are a floor, and that results are ordered most recent first. This goes beyond the annotations and gives the agent a realistic expectation of output completeness. 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 four sentences, but every sentence earns its place: core action, usage, coverage caveat, and sibling differentiation. It is front-loaded with the main purpose and avoids filler. This is efficient, information-dense writing.

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 citation-search tool with no output schema, the description covers all critical aspects: what it does, how to use it, the important coverage limitation, alternatives, and distinction from a similar sibling. It even mentions output content ('full citation metadata'). The agent has enough context to invoke it correctly and interpret results.

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

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

Schema coverage is 100% for both parameters (pmid and limit), so the baseline is 3. The description only says 'Pass one PMID' which echoes the schema, and adds no deeper semantic meaning (e.g., format specifics or edge cases) beyond what the schema already provides. The schema itself is sufficiently descriptive.

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

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

The description opens with a specific verb and resource: 'Find papers that CITE a given article — forward citation search.' It clearly distinguishes from the sibling tool get_related_articles by explicitly stating it returns citing papers, not similar papers. This is an unambiguous, well-scoped purpose.

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

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

The description provides explicit use cases ('who cited this', 'has this finding been replicated or challenged', 'tracking downstream impact') and explicitly names alternatives for broader citation coverage (Semantic Scholar/OpenAlex). It also contrasts with get_related_articles, giving clear when-to-use vs. 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 indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: PMID resolution to PMC ID, output capped at ~40k chars, and the has_full_text:false fallback signal. This goes well beyond the annotation hints.

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

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

The description is three sentences, front-loaded with purpose, then usage direction, then technical limitations. Each clause carries necessary information without redundancy. Quotes and examples are compact and helpful.

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 no output schema, the description fully covers what an agent needs: purpose, when to use vs. sibling, PMC-only limitation, character cap, and fallback behavior. No gaps remain for successful invocation and interpretation.

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%, describing the single pmid parameter and noting it accepts either a PubMed ID or a PMC ID. The description adds the resolution context (PMID→PMC) but inaccurately implies only PubMed IDs are accepted, omitting the PMC ID alternative explicit in the schema. This is a minor contradiction that reduces the score from a possible 4.

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

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

The description opens with a specific verb and resource: 'Fetch the FULL TEXT of a biomedical paper from PubMed Central...' and immediately distinguishes itself from sibling get_abstract by referencing methods/results/discussion vs abstract. It explicitly names the sibling tool, 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?

Provides explicit when-to-use guidance: 'PREFER OVER get_abstract when you need methods/results/discussion, not just the abstract' with concrete example queries. Also gives an exclusion criterion: only open-access articles are in PMC, and directs fallback to get_abstract when has_full_text is false.

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 and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context: the relevance ranking mechanism, the return of full citation metadata (title, authors, journal, date, DOI), and the requirement of a single PMID. It stops short of discussing edge cases or rate limits, but given the strong annotation coverage, this is sufficient.

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

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

The description is three well-structured sentences: purpose, usage, and differentiation from a sibling. It is front-loaded with the core action, every sentence adds value, and there is no redundant wording.

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 read-only, idempotent lookup with no output schema, the description covers all necessary context: input (single PMID), output (related papers with citation metadata), ranking logic, and the distinction from get_citations. The openWorldHint and readOnly annotations further contextualize its behavior, making it 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 coverage is 100% — both pmid and limit are fully described with types, defaults, and examples. The description mentions passing one PMID and returning top related papers, but it does not add any new parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Find papers SIMILAR to a given article' — a specific verb targeting a clear resource — and further specifies the algorithmic basis (pubmed_pubmed neighbors, ranked by relevance using shared terms/MeSH/citations). It also explicitly distinguishes itself from the sibling tool get_citations, making its purpose unmistakable.

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

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

It gives explicit use cases: 'more papers like this', building a reading list, broadening a literature search beyond keyword matches. It also names the alternative get_citations and explains what that tool does differently ('finds papers that cite this one'), 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds the batch limit (~200 IDs), a cost hint, and the source context ('from search_pubmed'), enriching behavioral understanding without contradicting 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?

Two concise sentences cover purpose, usage, batch details, and an alternative. Every clause adds value, with the most important information 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?

For a simple one-parameter tool with comprehensive annotations and an output schema, this description is complete. It covers what the tool does, when to use it, how to batch, and what not to use it for (abstracts).

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

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

The schema already provides 100% coverage by describing 'ids' as a comma-separated string. The description adds context by mentioning the size limit (~200) and the recommendation to batch, and even connects it to search_pubmed, which helps the agent understand how to obtain valid IDs.

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 specific verb 'Resolve' and the resource 'PubMed IDs' to 'citation metadata', enumerating the fields returned (title, authors, journal, publication date, DOI). It distinguishes itself from siblings by noting 'for the abstract text use get_abstract instead', making the tool's purpose unmistakable.

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

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

It explicitly states when to use the tool ('Use when you have PMIDs and need the citation') and provides a direct alternative ('for the abstract text use get_abstract instead'). It also provides batching guidance ('Batch up to ~200 IDs per call') and a cost rationale ('much cheaper than calling per-ID'), which helps agents choose it efficiently.

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 and destructiveHint=false, and the description adds the return fields (id, type, params, created_at, last_fired_at, fire_count) along with the fact that it lists active subscriptions. This goes beyond the annotations by giving a clear picture of the output without contradicting them.

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

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

The description is two sentences, with the main action first, followed by the output fields and usage guidance. Every sentence adds value, and the structure is highly scannable.

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 explicitly lists the returned fields, compensating for that gap. Combined with the one optional parameter and strong annotations, this description fully covers the tool's context and behavior.

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

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

Schema description coverage is 100%, and the single parameter include_inactive has a clear description in the schema. The tool description does not add additional parameter semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('List the caller's active subscriptions') and clearly distinguishes itself from sibling tools by stating it lists existing subscriptions rather than creating or canceling them. It also explicitly mentions the use case for canceling, reinforcing its purpose.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool (before subscribing more or when needing an ID to unsubscribe) without needing to infer from sibling names.

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 are all false and provide no meaningful safety or behavior clues, so the description carries the full burden. It discloses the claim_token flow for anonymous filing, how to later check on a report, rate limits (5/day), quota exemption, and team reading cadence. This is rich behavioral context beyond what annotations offer.

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

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

The description is lengthy but every sentence delivers unique information: purpose, use cases, exclusions, token flow, rate limit, and quota note. It is front-loaded with the core purpose and contains no redundancy or fluff, making the length appropriate for the tool's complexity.

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

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

With no output schema, the description explains the return behavior (claim_token) and the follow-up mechanism, which is essential. It covers scope, constraints, operational details, and the feedback workflow, making the tool fully comprehensible without additional documentation.

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

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

Schema coverage is 100%, setting a baseline of 3. The description adds value beyond the schema by clarifying the claim_token parameter's role in retrieving earlier reports and by instructing that the message should reference Pipeworx tools/packs rather than pasting end-user prompts—details the schema does not include.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the verb, resource, and scope. It distinguishes from sibling tools by explicitly limiting feedback to tools served by this Pipeworx connection, a concern no other sibling addresses.

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 when to use: bug, feature/data_gap, praise, and when not to use: if the tool came from a different MCP server, with a direct alternative ('file it with that server instead'). It also gives guidance on how to describe the issue, leaving no ambiguity about invocation conditions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavioral context: it is self-aggregating, derived from the CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This adds real value beyond what annotations state and fully characterizes the tool's behavior.

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

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

The description is compact and front-loaded: the first sentence states what the tool returns, and the following sentences and bullets add practical use cases and behavioral caveats. Every sentence earns its place with no fluff or repetition of the title.

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 only one optional parameter, a rich schema, and strong annotations, the description fully covers what an agent needs: purpose, return content, use cases, data source, privacy, and caching behavior. There is no output schema, but the description adequately specifies what will be returned (top tools, top packs, total call volume), making it complete for selection and invocation.

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

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

The schema already fully documents the single `window` parameter (100% coverage) with enum values and default, so the baseline is 3. The description adds extra semantics by explaining that shorter windows surface what's hot right now while longer windows show steady-state demand, and it ties caching duration to the window choice, going beyond the schema.

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

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

The description uses a specific verb ('Returns') and names the exact resource: top tools, top packs, and total call volume over a recent window. It clearly positions itself as a trending/aggregation tool, distinct from sibling tools like ask_pipeworx or discover_tools by focusing on what other agents are calling. The three bullet use cases reinforce the unique purpose.

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

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

The description provides explicit 'Useful for' guidance with three concrete scenarios, which gives clear context for when to invoke this tool. It stops short of naming alternative tools or stating when not to use it, so it misses the full 'when-not' guidance that would earn a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, destructive=false), the description discloses key behavioral rules: threshold for signal emission (>3pp deviation), placeholder filtering (>20% returns null arb signal), fill-check semantics (realizable_edge_pp ≤ 0 means do not trade), and how the partition sum is computed. This gives the agent a clear picture of when the tool will and won't produce actionable signals.

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

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

The description is long but well-organized, with clear sections for event mode, topic mode, semnantic anchor, partition filter, response format, and fill check. Every sentence contributes technical detail needed to use the tool correctly. While dense, the structure makes it scannable and justified for a complex tool.

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

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

With no output schema, the description fully specifies the response shape: opportunities[] with fields, partition_check object, and fill_check details. It also covers edge cases like null arb signal and the 'do not trade' condition, making the tool's behavior clear even without a 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% with detailed descriptions for both `event` and `topic`, so the baseline is 3. The description adds value with concrete examples of event slugs and seed questions, and clarifies when each mode is most appropriate. However, the schema already covers the core semantics, so the increment is modest.

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 opening sentence clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific resource (Polymarket) and method (monotonicity + partition-sum), and distinguishes the three invocation modes (trending_scan, event, topic) with distinct 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?

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. Also recommends event 'for a specific market' and topic 'for cross-event scanning'. Points to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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 only indicate read-only and idempotent behavior, but the description goes far beyond by detailing algorithmic specifics (lognormal barrier, GDELT ratio, overround partitions), the 24h-move warning, why Fed bets are excluded, and the 1-hour KV caching. This provides deep transparency into how the tool behaves internally and what to expect in the response.

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 long and dense, though it uses section labels (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) to organize content. It front-loads the main purpose but then dives into extensive algorithmic detail that could be trimmed or moved elsewhere. While the thoroughness is valuable, it's not 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 complex tool with 9 parameters and no output schema, this description thoroughly covers response structure (by_segment, fed_candidates, _diagnostics), filtering behavior, edge calculation, and even why certain segments might be empty. It leaves no significant gap for an agent to understand what this tool does and what it returns.

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

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

Schema descriptions cover all 9 parameters (100% coverage), so baseline is 3. The description adds extra nuance beyond the schema, such as explaining that min_partition_leg_kelly applies to per-leg Kelly because partition arbs always return parent-level Kelly 0, and clarifying the slippage_pp default in context of Polymarket's zero fees. This adds meaningful semantic value on top of the schema.

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

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

The description states a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings by emphasizing the Pipeworx data signal and five model families, which is unique among tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly states the intended use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and provides guidance on when to adjust knobs (e.g., 'Set to 5000 to drop thin-book opportunities'). It does not name alternative tools or exclude scenarios, but the context is clear enough for an agent to decide when to invoke this tool.

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

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

Beyond annotations, the description explains the response structure, the meaning of snapshot gaps, TTL limits, and that decay is computed on daily closes of edge_pp_net (net of slippage). It also clarifies the signed edge_pp_net interpretation. This is rich behavioral context that goes well beyond readOnlyHint.

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

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

The description is long but well-structured with Args, RESPONSE, and LIMITS sections. It packs detailed information without tautology, 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?

With no output schema, the description thoroughly documents the return structure (tracked, expired, snapshot_dates) and their fields, plus data availability caveats. It is complete for an agent to invoke correctly.

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

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

The schema already documents both parameters (days, window) with defaults and ranges. The description reiterates the same info without adding new semantics. Baseline 3 applies.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It 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?

It gives clear context: 'Answers "how long has this edge existed and is it shrinking?"' and explains its relationship to daily snapshots. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes far beyond: it explains the tool 'walks the ladder', lists exact return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that 'partial basket fills convert an arb into an unhedged directional position.' This provides nuanced behavioral context beyond the safety hints.

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

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

The description is dense but well-organized, moving from core purpose to mode-specific details to usage guidance. Every sentence adds new information, though the length is considerable. The front-loaded definition makes the main function immediately clear, so it earns a high score despite its size.

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 must explain return values, and it does: both modes list all returned metrics (verdict, capture_ratio, thin_legs, etc.). It also covers conditional requirements (market OR event), parameter defaults, and risk warnings. For a tool of this complexity, the description is exceptionally 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 coverage is 100%, so baseline is 3, but the description adds substantial value: clarifies that `market` and `event` are mutually exclusive modes, explains `side` defaults and logic (auto for basket), and defines `size_usd` as 'settlement notional S (shares per leg)' with clamp range. This enriches the schema without redundancy.

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

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

The description opens with a precise verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by naming its role in the workflow (check before arbitrage or edge trades) and details both single-market and basket modes, making the purpose unmistakable.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged directional risk), and contrasts with alternatives. This is textbook usage guidance.

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

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

Beyond the readOnlyHint=true annotation (which already indicates safety), the description discloses rich behavioral detail: it describes compatibility_warning conditions, how skipped_cross_type/subtype affect results, and the meaning of temporal_alignment. It warns that most pre-mapped topics return compatibility_warning today. This is far beyond what annotations provide and sets realistic expectations.

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

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

The description is lengthy but information-dense, with clear structural markers ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') that aid scanning. Every sentence adds either a functional detail or a safety caveat. It earns a 4 because it is larger than ideal for quick ingestion, yet it earns its space given the tool's complexity.

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

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

With no output schema, the description must explain return values — and it does: 'each venue's leg-by-leg prices... plus matched spread[].top_spreads_pp'. It also covers edge cases (compatibility_warning scenarios, skipped_cross_type meanings, temporal alignment) that would otherwise be opaque. For a tool with 3 optional parameters and complex output semantics, the description is exceptionally 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 schema already covers all 3 parameters with descriptions and 100% coverage. The description adds value by explaining the two execution modes and the override interaction between topic and explicit tickers/slugs. It also encodes the valid topic values within the description, reinforcing the schema. A score of 4 is warranted since the description enriches the parameter semantics without redundancy.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by naming both venues and the exact comparison being made. The two modes (topic shortcuts vs explicit tickers) further sharpen the intended functionality.

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 explains when to use each mode: 'TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings.' It also gives important usage caveats: 'pre-mapped ≠ tradeable' and explains when spreads are 'mathematically meaningless' (temporal_alignment:false). This is clear, actionable guidance for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable interpretative context beyond annotations: counts are 'publication-index signals, not efficacy, quality, independence, or clinical-success judgments.' This prevents misinterpretation of the tool's output and clarifies what the counts do and do not represent.

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

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

The description is two sentences, front-loaded with the action and resources, followed by usage guidance and a critical caveat. Every phrase earns its place with zero redundancy. This is a model of concise, high-signal description writing.

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

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

The tool is a simple counting operation, and the description covers purpose, usage, and interpretation. It doesn't describe the exact output format, but the phrase 'counting... publication types' implies counts per category. Given the low complexity and strong annotations, the description is sufficiently complete, though it could optionally mention that results are grouped by type.

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

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

Schema coverage is 100%, with each parameter described and an example provided. The description doesn't add parameter-specific syntax but doesn't need to, as the schema carries the heavy lifting. Baseline 3 is appropriate; the description's mention of 'for a topic' maps to the query parameter, but adds no extra semantic depth beyond the schema.

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

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

The description uses a specific verb ('Profile the composition') and names the exact resource ('PubMed publication types'), listing the study types counted. This clearly distinguishes it from siblings like search_pubmed and pubmed_publication_trend, and the evidence-diligence use case reinforces its unique scope.

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 it: 'Use for evidence diligence and questions like "what kinds of studies exist on this target or therapy?"'. While it doesn't name alternatives or state when not to use it, the context is clear and directive. Sibling tools like search_pubmed are implied as alternatives for different tasks.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful caveats: it reports only relationships present in PubMed, and absence of a flag is not independent validation. This goes beyond the annotations by clarifying the tool's epistemic limits and output interpretation.

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 deliver the core function, a use case, and a crucial caveat. Every sentence contributes distinct value; no redundancy or padding. Information is front-loaded in the first sentence.

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

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

The tool is simple (one param, no output schema). The description explains what integrity flags are checked, when to use it, and how to interpret results (reports only existing relationships; absence not proof). While it doesn't describe the exact output format, the behavioral caveat provides sufficient return semantics for an agent to select and expect results.

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

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

Schema coverage is 100% for the single parameter 'pmid', described as 'A single numeric PubMed ID.' The description does not add new parameter-level details beyond reinforcing that it operates on one PMID. Baseline of 3 applies given 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 clearly states the tool's function: checking one PubMed citation for specific NLM-indexed integrity flags (retraction, expression of concern, erratum, update, duplicate publication, republished articles). The verb 'Check' plus enumerated link types uniquely scopes this tool relative to siblings like search_pubmed or get_abstract.

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

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

Explicit usage guidance is given: 'Use before relying on a specific PMID in diligence or evidence synthesis.' This provides a clear context for when to invoke the tool. It does not explicitly name alternatives or when-not cases, but the instruction is actionable and distinct from sibling tools.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral context: returns 'exact PubMed search counts for up to 10 calendar years' and warns that volume 'can reflect indexing and terminology changes and is not evidence quality or commercial validation.' This manages expectations and prevents misinterpretation of the output.

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

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

Three sentences, with the action in the first sentence. All additional sentences are purposeful: one provides usage scenarios, the other describes output limitations. There is no fluff or repetition of schema details.

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

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

Despite having no output schema, the description explicitly states the return value ('exact PubMed search counts for up to 10 calendar years') and caveats. Combined with schema descriptions and safety annotations, the tool is fully specified for an agent to invoke and interpret results correctly.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters. The description adds extra meaning by mentioning the 10-year limit, which clarifies the effective range of from_year/to_year. This goes beyond the schema's generic 'first year' and 'last year' descriptions.

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

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

The description opens with a specific action and resource: 'Count PubMed publications by year for a biomedical topic.' This clearly distinguishes it from sibling tools like search_pubmed (which retrieves articles) or pubmed_evidence_landscape (which assesses evidence quality). The verb 'count' and the temporal scope are explicit.

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 for publication momentum, emerging-target activity, or whether a field is accelerating or cooling.' This gives clear context for when to choose this tool. It does not explicitly name alternatives or state when not to use it, hence not a 5.

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

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

Annotations already confirm read-only and non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the dual behavior of returning a single value or all keys, which annotations do not convey.

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

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

Three sentences, front-loaded with the primary function, followed by use cases and scoping/pairing. No redundant wording or filler.

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

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

Despite having no output schema, the description explains the return semantics ('retrieve a value' or 'list all saved keys'), covers scoping, and references sibling tools. Combined with annotations, it is fully adequate for this simple one-parameter tool.

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

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

The schema documents the 'key' parameter with 100% coverage, but the description enriches it with real-world examples (ticker, address, research notes) and explains the key's namespace through the scoping statement, adding 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 opens with a specific action ('Retrieve a value previously saved via remember') and lists the secondary mode ('list all saved keys'). It names the resource (memory stored by remember) and distinguishes from sibling tools by describing the save/retrieve/delete lifecycle.

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 says 'Use to look up context the agent stored earlier' and gives concrete examples (ticker, address, research notes). It also states pairings 'Pair with remember to save, forget to delete,' making the alternative tools clear.

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

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

Annotations already mark readOnly/openWorld/idempotent hint, so the bar is lower, but the description adds valuable behavior: the persistence of the feed, the mark_read effect on subsequent calls, and the polling-friendly nature. It clearly explains side effects (modifying read state) without contradicting the read-only annotation, since mark_read mutates read flags only.

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

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

The description is three sentences and every clause earns its place: what is returned, the payload contents, filtering, mark_read side effect, and alternative endpoint. It is front-loaded with the core action and remains highly readable.

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

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

Given no output schema, the description must convey return shape, and it does: source, citation_uri, raw event payload. It also covers all key parameters (type, since, mark_read) and mentions limit indirectly via query context, making it sufficiently complete for a tool with 5 optional parameters.

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

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

Schema coverage is 100%, so baseline 3. The description exceeds baseline by explaining the purpose of mark_read ('flag returned events read so the next call only shows newer ones') and gives a concrete type example ('sec_8k'), adding nuance beyond the schema descriptions.

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

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

The description opens with the specific verb 'Pull' and identifies the resource as 'fired events from your subscription feed.' It clearly distinguishes from sibling tools like list_subscriptions or recent_changes by describing the returned payload (source, citation_uri, raw event) and the filtering options.

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

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

It gives clear context: polling works, and the feed is also available at a direct GET endpoint for scripts/dashboards. This implies the tool is suitable for interactive/Agent use while the endpoint is for automation. However, it does not explicitly state when to choose this over a sibling tool like recent_changes or list_subscriptions, only the alternative HTTP access.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses rate-limit fallback (GDELT → GNews), soft-failure of the PatentsView API due to sunset, output structure (changes[], total_changes, citation URIs), and parameter semantics. No contradictions.

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

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

The description is dense but every sentence is informative: query examples, source behavior, fallback details, API sunset note, output summary, and alternative tool. It is front-loaded with use cases and uses a readable, structured flow despite being a single paragraph.

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—multi-source fan-out, fallback logic, parameter nuances, and no output schema—the description fully covers what the agent needs to know: return shape, source-specific behaviors, time-window parsing, and when to prefer another tool. No significant gaps remain.

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

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

The description explains `since` accepts ISO dates or relative shorthand ('7d', '3m') and recommends typical monitoring values ('30d' or '1m'). It also clarifies `value` can be a ticker or zero-padded CIK. This adds significant meaning beyond the schema, which already covers all parameters.

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

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

The description clearly states it provides a change feed for a company over a time window, using multiple query phrasings. It explicitly distinguishes itself from entity_profile, which focuses on static profiles, making it easy to know when to choose this 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?

The description is explicit about when to use this tool (recent changes over N days/weeks/months) and gives an exclusion: use entity_profile instead when wanting a static profile. It also explains the source fan-out and fallback behavior, helping the agent decide appropriately.

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 a non-destructive write (readOnly=false, destructive=false) and idempotence. The description adds persistence details (authenticated vs anonymous 24-hour retention) and scoping by identifier, enhancing transparency, though it doesn't address overwrite behavior or limits.

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

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

Four sentences, each covering a distinct aspect: purpose, usage, persistence, and related tools. Slightly longer than minimal but well-organized and free of redundancy.

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

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

For a simple store tool with full schema and annotations, the description covers purpose, usage, persistence, and sibling relationships. Minor omissions like overwrite behavior or value size limits don't significantly impair understanding.

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 both key and value with examples, so baseline is 3. Description adds the concept of scoping by identifier but doesn't provide parameter-specific detail 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 saves data for later reuse, specifying a key-value pair. It also distinguishes itself from recall and forget by naming them as complementary 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?

Provides explicit conditions for use ('when you discover something worth carrying forward') with concrete examples, and mentions pairing with recall/forget for retrieval/deletion, establishing when to use alternatives.

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

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

The description adds significant behavioral context beyond annotations: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels identifiers by source, and states unresolved identifiers are included explicitly. This aligns with the readOnlyHint and idempotentHint 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 purpose and usage guidance, then dives into specifics. It is somewhat verbose (e.g., the company type explanation is detailed), but every sentence adds value for an agent. Could be slightly trimmed without losing clarity.

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

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

Given no output schema, the description compensates by describing what the output contains (identifiers, sources, unresolved). It covers both supported types and graceful degradation. It is complete enough for an agent to understand inputs and expected outputs, though a structured output schema would be ideal.

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

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

Schema coverage is 100%. The description adds details: for 'value' it explains accepted formats (ticker, CIK, ISIN, name) and special ISIN-to-LEI mapping; for 'type' it explains resolution behavior for company and drug. This provides meaning beyond the schema's enum and 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 explicitly states that the tool resolves a user-spoken name to canonical/official identifiers needed as input for other tools. It provides example queries and clearly differentiates from siblings like compare_entities or entity_profile by focusing on identifier lookup.

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 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It also explains it can replace 2-3 manual lookups. It does not explicitly mention when not to use it or provide alternatives, but the context is sufficient for an agent.

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

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

Beyond the readOnly and idempotent annotations, the description adds meaningful behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This enriches the agent's understanding of what the tool does.

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, zero filler. The main purpose leads, followed by process, use case, and output specification. Every sentence carries information.

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

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

For a multi-entity comparison tool with no output schema, the description fully covers the return value ('ranked list with score, confidence, signal density'), the workflow, and the primary use case. The schema covers parameter details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the description need not repeat parameter details. The description adds no extra meaning beyond the schema (e.g., it doesn't clarify the 'entities' ordering beyond what schema already says about first being subject). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'Compare' and the resource 'AI visibility across entities,' and distinguishes from sibling ai_visibility_check by mentioning it probes each entity and ranks results.

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 a concrete use case ('Useful for competitive AI-marketing audits') and implies it is for multi-entity comparison versus the single-entity ai_visibility_check sibling. However, it does not explicitly state when NOT to use it or name alternative tools.

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

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

Annotations already declare readOnly and idempotent, but the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This goes beyond the safety profile and describes failure modes and latency.

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

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

The description is dense and clearly structured: purpose, usage, output fields, caveats. Each sentence earns its place, though the run-on first sentence could be split. No filler or repetition of annotations.

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

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

This is a complex composite tool with no output schema, yet the description enumerates the return fields (summary block, per-advisory detail, links, recent versions), explains ecosystem scope, and covers edge cases like timeouts. It gives agents enough information to set expectations and handle partial results.

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

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

Schema description coverage is 100%, so the schema fully documents package and version parameters. The description reinforces the scope (npm package) and mentions scoped packages, but does not add meaning beyond the schema's existing descriptions. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: a composite 'should I add this npm package' check in ONE call. It names the data sources (deps.dev, bundlephobia) and clearly differentiates from sibling tools like scan_competitor_ai_presence by focusing on package risk/size evaluation.

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 it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding users toward the correct tool for non-NPM packages.

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?

Even with annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: it clarifies the tool searches by keyword/author/MeSH, supports field qualifiers, and returns only PubMed IDs rather than full citations. It also establishes an authoritative source and scope, which goes beyond the annotation hints.

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

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

The description is longer than a typical two-line tool description, but every sentence adds practical value: preference over web search, coverage scope, usage examples, query syntax, and return type. It is front-loaded with the most important guidance and structured well, though it could be trimmed slightly (e.g., the enumerated specialty list) without losing core 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?

The description is complete for a search tool: it explains what the tool returns (PubMed IDs), how to construct queries, what the output feeds into, and the intended domain. It names the sibling tools that consume its output, making the overall search-resolve workflow understandable. The presence of an output schema means the return shape need not be spelled out in prose.

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?

Although the input schema covers both parameters (query and limit) at 100%, the description adds meaningful semantics for the query parameter with examples ('Smith J[Author]', 'COVID-19[MeSH]') and explains the range of MeSH/keyword/author queries. This enriches the schema's basic description and supports correct query formulation.

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

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

The description clearly identifies the tool as a search over PubMed with a specific verb ('Search Pubmed') and resource ('NIH PubMed'). It distinguishes itself by explicitly saying to prefer it over web search for biomedical topics and by explaining its relationship to sibling tools (returns IDs that pubmed get_summary/get_abstract 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?

The description explicitly states when to use this tool ('PREFER OVER WEB SEARCH for biomedical / clinical / life-sciences research') and gives concrete use cases with examples. It also points to downstream tools (get_summary/get_abstract) for resolving the returned IDs, implying the typical workflow and when other tools would be used.

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

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

Goes well beyond the readOnly/idempotent/destructive annotations by revealing the underlying mechanism (BGE-base-en embeddings + cosine over 500-char overlapping windows), the 200K-char cap with truncation-and-flag behavior, and the output structure (passages with offsets and similarity scores). This gives the agent a robust mental model.

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?

Four dense sentences, each serving a distinct purpose: core action, use case, sibling pairing, and technical edge-case behavior. Front-loaded with the most critical information and no filler.

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

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

Since there is no output schema, the description must explain return values, and it does: 'top-N passages with character offsets and similarity scores.' It also covers the oversized-input truncation behavior. For a 3-parameter tool, this is fully self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing realistic examples for 'text' (SEC 10-K body, article, long tool result) and clarifying the truncation edge case for the 'text' parameter. It also gives a concrete query example, slightly exceeding the schema's own descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly stating a specific verb+resource and distinguishing it from siblings. It explicitly contrasts with ask_pipeworx_grounded, framing search_within as a passage-level retrieval tool versus whole-document grounding.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context). Also details a concrete workflow pairing with ask_pipeworx_grounded, making the usage context 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?

Despite annotations already indicating non-read-only and idempotent, the description adds rich behavioral context: OAuth account requirement, anonymous/BYO cannot persist, returns the subscription id, SMS phone verification with a 10/day cap, and webhook auto-disable after 10 consecutive failures. 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?

Though dense, every sentence earns its place: purpose, return value, auth requirement, supported types with examples, and delivery options. The structure is logical and front-loaded with the core action.

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

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

The description covers auth requirements, return value, all supported types, delivery channels, and even points to the always-on feed retrieval via recent_alerts or a registry URL. Combined with the detailed schema, nothing essential is missing for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples like items:['5.02'] for sec_8k and topic:'fed' for polymarket_edge, plus delivery semantics like phone verification and rate caps, going beyond schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and specifying supported alert types.

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

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

The description implies usage for ongoing monitoring and explicitly mentions 'pull via recent_alerts' for the always-on feed, differentiating creation from retrieval. It does not explicitly name alternative tools like list_subscriptions as exclusions, but the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond these: it returns category-bucketed example questions with tool+argument shapes drawn from a live catalog of thousands of tools. It also explains that calling with no arguments yields the full spread while passing a topic focuses results, which is behavioral detail not covered by 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 efficiently structured with a clear lead-in of example user queries, followed by the tool's purpose, return value structure, calling convention, and explicit usage priority. Every sentence carries essential information, and the front-loaded examples make it immediately apparent what the tool does. 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 has only one optional parameter and no output schema, the description is fully complete. It explains the output content (category-bucketed example questions with tool+argument shapes), the source (live catalog), the no-argument versus topic-focused modes, and when to use it first. It also proactively references meta-tools that the agent should learn, covering the full context an agent needs for onboarding.

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

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

The schema already covers the `topic` parameter with a description and valid values, so baseline is 3. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explaining the contrast between full spread (no arguments) and focused results (with topic), which helps the agent decide how to invoke the tool. It doesn't reach 5 because the schema already lists all valid topics and the description doesn't introduce additional parameter-related semantics.

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

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

The description clearly states this is the onboarding entry point for agents wanting to know what they can ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and by referencing meta-tools like ask_pipeworx, entity_profile, and compare_entities, making its unique role clear.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also clarifies when to omit or pass the `topic` parameter, and contrasts with alternatives by naming the meta-tools it teaches.

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

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

Beyond the annotations (idempotentHint, destructiveHint), the description discloses the soft-delete behavior and ownership restriction. This adds meaningful context about the side effects and data preservation, which annotations alone don't fully convey.

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

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

Two concise sentences front-load the action ('Cancel a subscription by id') then add key nuances. 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?

For a one-parameter tool with no output schema, the description covers the essential behavior: ownership, deactivation, and historical data preservation. It references recent_alerts, providing sufficient operational context for an agent.

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

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

Schema coverage is 100% with the id parameter already described as 'Subscription id (uuid) returned by subscribe.' The description only says 'by id' without adding further parameter detail, so it meets the baseline but doesn't enhance semantics.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings by clarifying ownership enforcement and the deactivation-vs-deletion behavior, making its purpose unambiguous compared to subscribe and list_subscriptions.

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

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

It provides clear context: ownership is enforced, and cancellation deactivates rather than deletes, preserving history via recent_alerts. This implies when to use it and what to expect, though it doesn't explicitly name alternative tools or 'when not to use' scenarios.

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

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

The description goes well beyond the annotations by disclosing important behavioral semantics: the meaning of each verdict, the special 'could_not_verify' case (check did not happen, not evidence), the 'unsupported' meaning, and the presence of verification_error{stage,detail}. It also reveals the internal routing logic between SEC/XBRL and the grounded pipeline, which is critical for callers to interpret results correctly.

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 rich but every sentence earns its place: paraphrase triggers, use instruction, pipeline explanation, return summary, caller-critical caveats, and efficiency note. It is well-structured with clear sections, and although lengthy, its density of actionable information justifies the length.

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

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

Despite having no output schema, the description covers the return value structure (verdict, actual value with citation, reasoning) and the critical edge cases (could_not_verify, unsupported) that an agent must understand to use the result properly. It also explains both processing paths and the efficiency advantage, making it fully complete for a tool of this complexity.

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

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

The input schema already provides thorough descriptions for both parameters, including examples for 'claim' and detailed guidance for 'tolerance_pct' (range, default, and use for hallucination detection). The description adds minimal additional semantics beyond the 'exact percent-delta math' mention, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with explicit natural-language paraphrase examples and states the core function: fact-checking claims against authoritative sources. It clearly distinguishes itself from generic research/query tools by specifying the two internal pipelines (SEC EDGAR for company financials, grounded pipeline for everything else) and by noting it replaces multiple sequential calls.

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 when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies scope by distinguishing company-financial claims from any other factual claim. However, it does not explicitly name alternative tools or when-not-to-use scenarios, though the coverage of all factual claims makes that less necessary.

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