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, open-world, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: it routes across 5,798 tools, fills arguments automatically, returns pipeworx citation URIs, and handles breaking news via live news routing. No contradiction with annotations was found.

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 average but each segment earns its place: preferred-use cases, trigger phrases, concrete examples, and escalation paths to siblings. There is minor redundancy in the repeated emphasis on 'current or historical data' and factual questions, but the overall structure is logical and front-loaded with the most important routing guidance.

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 broad one-parameter question-answering tool, the description explains what input to give, what the tool will do internally, and what the output will look like (structured answer with citation URIs). It also covers when not to use it and which sibling to use instead, making it adequately complete despite having no output schema.

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

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

Schema coverage is 100%, with six documented aliases all describing the same 'question' input, so the schema already carries parameter meaning. The description contributes natural-language examples and clarifies that the system will fill arguments on its own, but it does not add new parameter-level detail beyond what the schema provides. A baseline of 3 is appropriate.

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

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

The description gives a concrete job: natural-language questions about real-world data are routed to a large verified-source tool network, arguments filled, and structured answers with citation URIs returned. It clearly distinguishes this tool from web search and from sibling alternatives like ask_pipeworx_grounded and deep_research. The verb 'routes' and the concrete source list remove ambiguity about what the tool does.

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

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

The description is unusually explicit: 'PREFER OVER WEB SEARCH' for a list of domains, with trigger phrases and examples. It also states when to step up to ask_pipeworx_grounded or deep_research, giving an agent a clear decision procedure instead of leaving it to infer.

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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about beta status, that no candidate is currently active, that it currently matches ask_pipeworx exactly, and that it is a full working router with no fallback. This exceeds what annotations alone provide 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 moderately detailed but each sentence earns its place: it explains the beta relationship, the current parity, the intended usage, and the absence of fallback. Slightly verbose phrasing such as 'Falls back to nothing — this IS a full working router' could be trimmed, but the structure front-loads the key information.

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

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

Given no output schema, the description usefully states that the response shape is identical to ask_pipeworx. It covers the tool's current behavior, relationship to siblings, and usage intent. For a beta router with experimental routing changes, this is complete enough for an agent to invoke it correctly.

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

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

Input schema coverage is 100%, with all parameters documented as aliases of question. The description does not add parameter-specific meaning, but it does confirm the same arguments as ask_pipeworx. Baseline 3 is appropriate because the schema already carries the parameter documentation burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and a universal router with the same tool set and response shape. It does not use an explicit action verb like 'answers' or 'routes', but it does distinguish this tool from the stable ask_pipeworx sibling and explains the experimental edge.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', which gives a concrete condition for choosing this tool over the stable router. It also explains the current status (no active candidate) and that results are compared against the stable router, making the selection context transparent.

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

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

Goes well beyond annotations by disclosing the exact success return shape, the possible refusal reasons, and the behavioral guarantee that answers are extracted only from tool results. It also flags the added cost of an extra LLM call, giving agents important operational 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 dense but each sentence adds important context: mode, routing, extraction behavior, return shape, refusal cases, usage guidance, and cost comparison. It could be slightly tighter, but it is front-loaded and free of 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 tool with no output schema, the description fully explains both success and refusal outputs, when to prefer it, and how it differs from its sibling. There is no missing information an agent would need to invoke it correctly or interpret its result.

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 documents the 'question' parameter and its aliases with 100% coverage, so the description need not repeat that. The description adds no additional parameter-level meaning, but the schema fully carries the burden, making the baseline 3 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 this as a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers strictly from returned tool data. It names the specific resource and differentiates itself from ask_pipeworx, so an agent can tell them apart without inspecting schemas.

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

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

Provides explicit guidance on when to use this tool: whenever an answer will be quoted, cited, or acted on, and fact invention is unacceptable. It also states when not to use it, recommending ask_pipeworx for casual lookups because of the extra LLM call cost.

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?

Annotations already mark the tool read-only and safe, so the description's job is to add behavioral context, and it does extensively: it returns gaps[] for unanswered facets, never invents findings, emits only fetchable citations, can return contradictions[], and can take 15–90 seconds. It also explains the depth-dependent execution behavior and passage-level semantic excerpting. No contradiction with the annotations exists.

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 it is dense and front-loaded: the account requirement and fallback tool appear first, then identity, then behavior, then edge cases. Each clause carries a distinct fact, and the only repetitions are intentional reinforcement of scope ("one call", "structured data"). This is appropriate for a tool with no output schema and several non-obvious behaviors.

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

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

There is no output schema, so the description correctly takes on the responsibility of explaining return values: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], and contradictions[]. It also covers prerequisites, alternatives, latency, and failure behavior. An agent has everything needed to decide whether to call it and what to expect back.

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

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

Schema coverage is 100% and the schema already documents both `question` and `depth` well. The description adds meaningful operational semantics on top: `depth:"thorough"` requires a paid plan, deeper depths add gap-recovery and lead-chasing passes, and runtime estimates differ by depth. This goes beyond the enum definitions without needing to repeat parameter syntax.

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 precise verb and resource: "Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources." It also draws a hard line against related tools with "this is NOT open-web search" and distinguishes make-or-break scope with "For a single lookup use ask_pipeworx." An agent can immediately tell what this tool is and what it is not.

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 decision boundary: "If you are not signed in, use ask_pipeworx instead — it works on every tier." It also defines the ideal use case: "Best for broad/multi-part questions over structured data" and the exclusion: "For a single lookup use ask_pipeworx." This is direct, actionable routing 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. 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?

Beyond the readOnly/idempotent/openWorld annotations, the description reveals meaningful behaviors: it fans out across many sources, soft-fails for the USPTO sunset, distinguishes 'no data' via sources_used/sources_failed, and explains why FDA biologics may legitimately be empty. No contradiction with annotations.

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

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

The description is long but front-loaded with usage triggers and 'ALWAYS PREFER.' Each source and return field earns its place given the tool's complexity and absent output schema, though the central sentence listing return keys is dense and somewhat hard to parse.

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 and two parameters, the description carries full responsibility for explaining return structure, source behavior, failure semantics, and edge cases. It covers resolved_from/resolved_to, sources_used/sources_failed, soft-failures, and private-company behavior comprehensively.

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

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

Schema coverage is 100%, but the description adds real value: it clarifies that 'company' and 'ticker' are interchangeable, gives examples of ticker/CIK/name values, notes zero-padding for CIKs, and explains that names resolve via SEC EDGAR company-name matching.

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 trigger phrases and states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this aggregator from chained single-source lookups, so an agent can identify when this tool applies.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides example user requests. It also explains the private-company case (resolved:false with notes) as an expected outcome rather than a failure.

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?

Annotations already declare readOnly and idempotent, and the description adds extensive behavioral detail beyond that: matching is keyword/overlap based, pairing is never verified against a shared resolution source, Kalshi fees are not modeled, unclassified legs are never paired, and temporal alignment can be unknown rather than aligned. This is exemplary disclosure of limitations and safety semantics.

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 unusually information-dense; nearly every sentence adds a distinct behavioral fact or caveat. The use of explicit labels like TWO MODES, SAFETY FIELDS, and Codes helps structure the information, though the single wall of text could be better organized for quick scanning.

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

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

There is no output schema, so the description must carry the burden of explaining return values, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment, skipped counters, and per-pair flags. For a high-complexity tool with ambiguous matching semantics and no structured output definition, this is a complete and highly informative description.

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 meaningful mode-level semantics: the topic parameter maps to pre-mapped shortcuts, explicit parameters override the mapped sides, and both modes run the identical matcher. This goes slightly beyond the schema's own descriptions, though it does not add much per-parameter type or format detail.

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 statement of function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, and clearly describes the two execution modes. It does not explicitly distinguish itself from siblings like polymarket_arbitrage, but the resource and outcome are concrete enough that an agent can tell what it does.

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

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

The description clearly explains when to use the pre-mapped topic mode versus explicit ticker/slug pairing, and warns that most pre-mapped topics currently return compatibility warnings and are not tradeable. It provides strong context and exclusions, though it does not explicitly route the agent to a named alternative tool.

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

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

Annotations already declare readOnlyHint, 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?

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral detail beyond that: identifiers that cannot be resolved are explicitly listed under `unresolved` rather than omitted, ambiguous name matches return `figi_candidates` without asserting, enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. No contradiction exists between description and 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 user-intent examples and the core 'name-to-ID' purpose, and nearly every sentence adds operational value. However, it is dense and heavily parenthetical, with long run-on clauses that make the structure harder to parse quickly. Still, the length is largely justified by the tool's complexity.

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

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

Given the tool's high complexity and lack of an output schema, the description is unusually complete: it specifies return identifiers (CIK, ticker, LEI, FIGI, RxCUI), source attribution, ambiguity handling, degradation behavior, and the `unresolved` field. An agent can correctly invoke the tool and interpret its results without needing extra 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?

Although schema coverage is 100%, the description meaningfully extends parameter understanding: for `value` it warns to pass the entity name only, explains that bond issuers must be passed exactly as printed and not with trailing security-class words, and details accepted forms (ticker, CIK, ISIN, brand/generic name). This prevents real invocation errors.

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

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

The description states a precise verb and resource: it resolves user-spoken names into canonical identifiers, with concrete example queries ('ticker for', 'CIK for', 'LEI for') and clearly enumerated supported types. It differentiates effectively by specifying that this tool provides the IDs that other tools require as input, positioning it apart from siblings like entity_profile and compare_entities.

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 guidance: 'Use FIRST whenever you have a name but need an ID,' and explains exactly which input kinds are accepted for company and drug. It does not name sibling alternatives or provide an explicit when-not-to-use case, but the usage context is clear enough for an agent to route to it.

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

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

Beyond the 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?

Annotations already declare the tool read-only, idempotent, and non-destructive; the description adds useful behavioral context by clarifying that it covers published literature, excludes trial registrations, and returns PubMed IDs that downstream get_summary/get_abstract tools can resolve. It does not mention rate limits or result freshness, but those are not critical given the existing annotations.

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

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

The description is front-loaded with the key preference and exclusion guidance, but the long coverage list and the later 'use it for' sentence overlap on the same biomedical topics and example domains. It is helpful but verbose; not every sentence earns its place.

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

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

Together with the schema and annotations, the description gives an agent everything needed to invoke the tool correctly: what it searches, what it excludes, how to formulate queries, and what it returns. Output details are not described in depth, but an output schema exists, so that is not a significant gap.

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

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

Schema coverage is 100%, and the schema already documents the query and limit parameters with examples. The description only restates that searches can use keyword, author, or MeSH, without adding meaningfully new detail about the parameters or their behavior, so baseline 3 is appropriate.

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

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

The description clearly states the tool searches PubMed, a specific authoritative resource, and that it finds published peer-reviewed papers and completed study results. It also distinguishes itself from web search and clinical-trials tools, so an agent can identify it unambiguously.

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 'PREFER OVER WEB SEARCH' for biomedical/clinical/life-sciences research and explicitly says it is NOT for browsing registered/ongoing/future clinical trials, pointing to clinicaltrials* tools instead. It also provides concrete example queries and use cases, giving the agent clear guidance on when to select 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?

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.