Gwas Catalog

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

Annotations already declare idempotent, read-only, non-destructive behavior. The description adds critical context: the default free model, the requirement for a BYO key for Anthropic, and the detailed return format per model (score, confidence, signals, raw_response) plus combined view. No contradictions.

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

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

The description is concise, consisting of three focused sentences. It is front-loaded with the main purpose and efficiently covers models, key usage, and return format without extraneous information.

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

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

Despite lacking an output schema, the description fully explains the return format. It covers all needed context for parameter usage, model selection, and use cases. The tool is well-documented 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?

Schema description coverage is 100%, but the tool description adds significant meaning beyond the schema by explaining the default model, the purpose of the API key, and how context helps disambiguation. The description enriches parameter understanding.

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

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

The description clearly states it probes LLMs to score visibility (0-100) per model, specifying the exact resource and action. It differentiates from sibling tools by focusing on visibility scoring across multiple models, which is unique among the listed siblings.

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

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

The description explains use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and when to provide an API key for Anthropic. However, it does not explicitly state when not to use this tool or suggest alternatives, which would strengthen guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it is a router that selects from 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This clearly informs the agent that the tool does meta-routing rather than direct execution, adding useful transparency.

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 key information is front-loaded and mostly relevant, but the description is verbose and contains redundancy: 'for broad multi-part research, use deep_research' appears twice in slightly different phrasing, and the extended list of domains/examples could be trimmed without losing meaning. This repetition makes the description less crisp than it could be.

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 still explains the return value ('structured answer with stable pipeworx:// citation URIs'). It covers scope, usage triggers, alternatives, input format, and the tool's internal behavior. For a router with one required parameter and comprehensive safety annotations, nothing essential is missing for an agent to decide when and how to invoke 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?

Schema description coverage is 100% since all six parameters are documented as aliases for 'question', so the baseline is 3. The description adds value by explaining that the natural-language question is passed to a routing engine that fills sub-tool arguments, and by providing realistic example queries ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') that illustrate what a valid parameter value looks like.

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 ('routes', 'returns'), a concrete resource ('5,798 tools across 1517 verified sources'), and a clear scope ('current or historical data' with a list of domains). It explicitly says 'PREFER OVER WEB SEARCH', which distinguishes it from generic search tools, and also differentiates it from sibling tools such as ask_pipeworx_grounded, entity_profile, and deep_research.

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

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

The description gives explicit triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current', factual questions), says to use it 'even if web search could also answer it', and provides a 'START HERE for most questions' directive with clear alternatives for different cases: ask_pipeworx_grounded for grounded single-answer, entity_profile for entity questions, and deep_research for broad multi-part research.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is already covered. The description adds context that candidate routing improvements may be live, that none are currently active, and that it matches ask_pipeworx exactly right now. However, it does not disclose potential behavioral differences when a candidate is active, such as nondeterminism or changed routing quality, which would be valuable for an experimental variant.

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

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

The description is a single dense paragraph that covers the beta status, relationship to the stable tool, current state, usage guidance, and fallback behavior. It is slightly long but every sentence carries information. The first sentence front-loads the most important fact: this is a beta version of ask_pipeworx.

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

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

Given the tool's simplicity (one required parameter, all aliases documented in the schema, no output schema needed because response shape matches ask_pipeworx), the description is largely complete. It explains current parity, the experimental nature, and how results are used. It could add a note about potential nondeterminism when a candidate is active, but that is a minor 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 description coverage is 100%, so the schema already documents all parameters, including the fact that q, text, input, query, and prompt are aliases for question. The description adds that arguments are identical to ask_pipeworx, which reinforces but does not extend the schema. Baseline 3 is appropriate given 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 identifies the tool as a beta variant of ask_pipeworx, a universal router with 5,798 tools, same arguments, and same response shape. It distinguishes it from the stable ask_pipeworx by noting candidate routing improvements may be active, though none currently are. It does not fully stand alone without referencing the sibling, but that is intentional and 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 explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide what merges. It also clarifies it is a full working router, not a fallback stub. This gives clear when-to-use guidance and distinguishes it from the stable sibling.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the exact success response shape, explicit refusal reasons, and the constraint that answers must come only from the tool result. It also reveals the additional LLM call cost, which is important behavioral context. Nothing contradicts 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 dense but efficient: every sentence adds decision-relevant information, from the high-stakes use case to routing behavior, return shape, refusal cases, and tradeoff vs. ask_pipeworx. The most important framing is front-loaded.

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

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

For a single-parameter tool with rich annotations and no output schema, the description fully covers selection criteria, invocation behavior, return/refusal structure, and cost tradeoffs. An agent has enough information to decide when to call it and what to expect from the response.

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%, so the schema already fully documents the single underlying question parameter and its aliases. The description adds routing and behavior context but no parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies a specific behavior: a hallucination-resistant answer mode that extracts answers only from tool results after routing and fetching. It distinguishes itself from ask_pipeworx by emphasizing groundedness, refusal behavior, and high-stakes use.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also names ask_pipeworx as the lighter-weight alternative and notes 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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details behavioral traits such as: it resolves the market, classifies the bet, fans out to category-specific data packs in parallel, and returns evidence. It also covers safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread tradeability), the resolver contract (market_match_confidence, alternatives, suggestions), and resolution-rule risk (cancellation_rule parsing). This provides a comprehensive behavioral profile that helps the AI agent understand exactly what the tool does and its edge cases.

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, etc.) that aid scanning. Every sentence provides unique value, covering classifiers, fan-out examples, response shapes, safety, and cancellation rules. The front-loading of the core purpose ('Research a Polymarket bet by pulling the relevant Pipeworx data') is effective. However, the description could be slightly more concise by merging some examples; nonetheless, the structure is clear and information-dense.

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 (3 parameters, no output schema, numerous edge cases), the description is exceptionally complete. It covers input formats, depth options, raw mode, classifiers, fan-out examples, response shapes (market, analysis, evidence, resolver contract, parent event, news fields), safety short-circuits, closed markets, wide spreads, and cancellation rules. The agent has all necessary context to use the tool effectively, including understanding the shape of the response despite the lack of an explicit 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% as all three parameters are documented. However, the description adds significant meaning beyond the schema: for 'market', it explains the three valid input formats (slug, URL, question text). For 'depth', it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out' and the default. For 'include_raw', it explains when to pass true (recompute deltas, cite observations, post-process) and the size implications. This extra context enables more informed parameter usage.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects. The verb 'research' combined with the resource 'Polymarket bet' and the action 'pulling Pipeworx data' makes the purpose specific and unambiguous.

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

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

The description explicitly 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".' It provides extensive guidance on when not to trust results (e.g., low-confidence resolution short-circuits, closed markets) and includes the resolver contract that agents must inspect. The fan-out examples also help agents understand which specific data sources are triggered for different bet types. This covers both when-to-use and cautionary notes.

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

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

Description adds significant behavioral context beyond annotations: detailed data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions with readOnlyHint etc.

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

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

Description is packed with useful information but slightly lengthy. Every sentence adds value, but could be trimmed slightly for brevity while retaining clarity.

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

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

For a tool with 2 parameters and no output schema, description explains what data is returned (revenue, net income, adverse events, trials), sorting, and citation URIs, ensuring complete 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?

Although schema coverage is 100%, description adds meaning: values for company are tickers/CIKs, for drug are names, with examples. This aids correct parameter use.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using verbs like 'compare' and example queries. It distinguishes from siblings like 'entity_profile' by explicitly recommending over sequential lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 sequential lookups. Example uses ('which is bigger', 'rank these') make context clear.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing the parallel decomposition across 5,798 tools, the exact findings packet structure, gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, resolvable citation URIs, and latency expectations. It also explicitly states the tool 'never invented' missing data. This is rich, specific behavioral disclosure.

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 severely bloated by the sentence 'For a single lookup use ask_pipeworx instead.' repeated dozens of times. While the opening is front-loaded with account requirements and the main definition, the extreme redundancy makes the description hard to parse and wastes significant token space. Every sentence does not earn its place; this is the opposite of 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?

With no output schema, the description carries the full burden of explaining the return value, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. It also covers authentication, paid depth tier, latency, and the structured-data-only scope. An agent has all essential information needed 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 coverage is 100%, so the schema already documents both parameters. The description adds extra semantic context: depth values map to hop counts, 'standard' performs gap recovery, 'thorough' chases leads and adds contradictions, and the question parameter supports broad/multi-part phrasing. This supplements the schema with practical behavioral nuances, though the core parameter meaning is already present.

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 and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' that 'decomposes your question into focused facets' and returns a findings packet. It explicitly differentiates from open-web search and names the sibling ask_pipeworx for single lookups, providing example multi-part questions. The purpose is clear and distinct.

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

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

The description explicitly tells when to use this tool: 'Best for broad/multi-part questions over structured data', and when not: 'For a single lookup use ask_pipeworx instead.' It also states the account requirement and that unauthenticated users should use ask_pipeworx, which works on every tier. These are direct, actionable routing instructions.

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, destructiveHint=false. Description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly, which adds value beyond annotations.

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

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

Description is well-structured, front-loaded with purpose. Could be slightly more concise, but every sentence adds value. Length is justified by the comprehensive examples and usage 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?

Given 6 parameters and no output schema, the description explains what the tool returns (names, descriptions, schemas, curated examples) and the calling order. Complete for discovery tool with clear annotations.

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

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

Schema covers 100% of parameters with descriptions. The description mentions aliases but schema already includes that. Baseline is 3 as schema does the heavy lifting; description adds minimal extra semantic value.

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

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

The description uses specific verbs like 'browse, search, look up, discover' and clearly identifies the resource (tools for specific domains). It distinguishes from sibling tools by being a discovery tool rather than a domain-specific tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Lists specific scenarios like SEC filings, financials, etc., providing clear context on when to use.

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

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

Despite annotations already declaring readOnly/openWorld/idempotent/non-destructive behavior, the description adds substantial beyond-schema context: parallel fan-out across multiple sources, sources_used/sources_failed reporting, soft-fail behavior for patents, resolved:false behavior for private companies, and expectations about empty sections. It also explicitly notes that a company with only small-molecule drugs will show no fda_products, which prevents false failure 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?

The description is long and dense, but the complexity of the tool justifies most of the content. It front-loads trigger phrases and the key 'always prefer' instruction, and every section contributes either selection guidance, input semantics, or return-value interpretation. It could be restructured with bullets for easier scanning, but it is not padded or redundant.

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 present, the description carries the full burden of explaining return values, and it does so thoroughly by enumerating the returned fields, the URI format for filings, fundamentals fields, each source category, and the sources_used/sources_failed mechanism. It also covers both valid input forms and the private-company edge case, making it complete enough for correct invocation.

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

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

Schema coverage is 100%, so the description need not repeat the schema, but it adds real value: concrete value examples ('AAPL', '0000320193', 'Moderna'), the interchangeability of type='company' and type='ticker', name resolution via SEC EDGAR, and the private-company resolved:false edge case. This meaningfully improves an agent's understanding beyond the raw input 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 this tool produces a full cross-source profile of a US public company in one parallel call, with explicit trigger examples like 'Tell me about X' and 'company profile for Microsoft'. It differentiates itself from single-pack SEC/XBRL/news lookups, so an agent can identify when this tool is the right holistic option.

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 instructs to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also gives clear context for when to use it versus narrower alternatives and explains how to interpret empty result sections, which is strong 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 provide destructiveHint=true, idempotentHint=true. Description adds no new behavioral traits beyond the 'Delete' action and 'clear sensitive data' context, which is more usage-related.

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

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

Two concise sentences: first states purpose, second adds usage guidelines. 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?

Given simple tool with one parameter, full schema coverage, and annotations, description is complete. Could mention return value or confirmation, but not necessary.

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 'key' parameter with description 'Memory key to delete'. Description adds no additional meaning beyond schema.

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

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

Clears purpose: 'Delete a previously stored memory by key.' Verb 'Delete', resource 'memory', scope 'by key'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicit guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data... Pair with remember and recall.' Tells when and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that it fetches the page, extracts title/description/key links, and emits standard format. No contradictions.

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

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

The description is concise: two sentences defining the action and one sentence listing use cases. It is front-loaded with the core purpose, no unnecessary words.

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

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

Given the tool's complexity and rich annotations, the description covers purpose, output format, and use cases adequately. Lacks details on error handling or edge cases, but is sufficient for an AI 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?

Schema coverage is 100% with both parameters described. The description does not add significant extra meaning beyond the schema, such as format constraints or error handling, 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 generates an llms.txt file for any URL, specifying the output format and use cases. It differentiates itself from siblings like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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

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

The description explicitly lists three use cases (indexing client site, drafting for own project, auditing competitor) providing clear when-to-use guidance. However, it does not explicitly state when not to use or name alternatives, though siblings imply other scanning tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=true. The description adds source (EBI/NHGRI) and keyless access, which provides some behavioral context but does not significantly extend beyond the annotations.

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

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

Two sentences with no fluff. Front-loaded with tool name and source, then details. Every word serves a purpose.

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

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

For a simple lookup tool with rich annotations and a single parameter, the description covers source, keyless access, and output content. Missing details on output format or error cases, but acceptable given annotations and 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 a single parameter 'rsid' well-documented in the schema (type, description, example). The description repeats 'by rsID' but adds no extra semantic 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?

Description clearly states it looks up a SNP by rsID from the GWAS Catalog, specifying the data returned (functional class, location, mapped genes). The verb 'look up' and resource 'SNP' are precise, and the context 'GWAS Catalog' distinguishes it from generic SNP retrieval 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?

No explicit guidance on when to use this tool versus alternatives like 'snp_associations'. The description mentions 'keyless' but does not address prerequisites, limitations, or scenarios where another tool would be preferred.

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 convey readOnly, idempotent, and non-destructive nature. The description adds that it returns specific fields and defaults to active subscriptions only, but no behavioral traits beyond what annotations provide. 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 two sentences with no wasted words. It front-loads the purpose and provides actionable guidance in the second 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?

With one optional parameter, no output schema, and rich annotations, the description covers all necessary context: what it does, what it returns, and a typical use case. It is fully sufficient for an agent to use this tool correctly.

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

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

Schema coverage is 100% for the single parameter 'include_inactive', which is well-described in the schema. The description does not add information about this parameter, so it adds no value beyond the schema.

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

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

The description clearly states the verb 'List' and the resource 'caller's active subscriptions', and lists the return fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by specifying it is for reviewing current 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?

The description explicitly advises when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context for appropriate usage, though it could contrast with alternatives more directly.

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

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

Discloses rate limiting ('5 per identifier per day'), the claim_token workflow for anonymous submissions and later status checks, and that it is free and doesn't count against quota. These behaviors go beyond the all-false annotations and give the agent a full picture of side effects and limitations.

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?

While a single long paragraph, it front-loads the core purpose and then systematically covers usage, exclusions, messaging guidance, token workflow, and rate limits. Every sentence adds information, and the density is justified by the tool's multiple operational facets.

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 and all annotations are false, the description carries the full burden—and succeeds. It explains the response (claim_token), the asynchronous resolution flow, and practical constraints, making it sufficient for an agent to use the tool correctly without further 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?

The input schema already provides 100% coverage with detailed enum and field descriptions. The description adds value by explaining how to frame the message ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and demonstrating claim_token reuse, reinforcing but not merely repeating 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 clear directive: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the resource (Pipeworx team) and distinguishes itself from sibling research tools by focusing on feedback about Pipeworx tools. The scope restriction to 'this Pipeworx connection' further clarifies its unique role.

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

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

Explicitly lists when to use: bugs, feature/data_gap, praise. Provides a clear exclusion: do not report tools from other MCP servers, with a redirect to file with that server. Also directs users to describe issues in terms of Pipeworx tools/packs, avoiding end-user prompts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, cached (5min-1h). This goes well beyond what annotations provide.

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

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

The description is concise (four sentences), well-structured: purpose first, then use cases, then technical details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional parameter, no required output schema), the description is fully complete. It explains return values, data source, privacy, and caching. No 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 single parameter 'window' has 100% schema coverage with enum and description. The description reinforces effective use (short vs long windows) and adds meaning about what each window reveals. Baseline is 3; the additional guidance raises it to 4.

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

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

The description clearly states the tool returns trending agent usage data: top tools, top packs, and total call volume. It specifies the resource (Pipeworx trending data) and distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregated agent call activity.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains how to choose between windows (short for hotness, long for steady-state). While it doesn't explicitly state when not to use it or list alternative tools, the context is clear enough for an agent.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds critical behavior: partition filter drops placeholder slugs, semantic anchor requires Jaccard similarity ≥0.30, and fill check against live CLOB depth. No contradictions.

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

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

While lengthy, every sentence adds value. Front-loaded with main purpose, then logically breaks down modes and details. Slightly verbose but well-structured for 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?

Comprehensive: explains multiple modes, edge cases (placeholder slugs, low similarity), output structure (opportunities, partition_check, fill check), and references sibling tool for custom sizing. No output schema, so description adequately covers return values.

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

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

Schema has 100% coverage with descriptions for both 'event' and 'topic'. Description significantly enriches by explaining exact usage (e.g., event slug format, topic seed question example) and provides behavioral details not in 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 explicitly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes between three modes (no args, event, topic). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique functionality.

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

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

Clear guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also advises when not to trade (realizable_edge_pp <= 0) and mentions polymarket_fill_risk for custom sizing.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: caching (1h at KV level), model details, slippage assumptions, Kelly sizing, 24h move warning, and reliability notes on Fed bets. This goes well beyond annotations.

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

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

The description is quite verbose with detailed model explanations but well-structured: purpose first, then segments, knobs, response. It front-loads key info. Some technical details could be trimmed for conciseness without losing clarity.

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

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

With 9 parameters and no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), caching, and edge attributes. It covers all aspects a user needs to understand tool usage and outputs.

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

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

Despite 100% schema coverage, the description adds significant context to each parameter, e.g., min_kelly explains it skips opportunities too small to bet, min_partition_leg_kelly clarifies why min_kelly doesn't apply to partition arbs, slippage_pp explains Polymarket fees and typical spreads. This enhances understanding beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on discovery without paging hundreds of markets, and provides detailed model family breakdown.

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 use case (betting opportunities) and provides guidance on knobs like min_liquidity and max_spread_pp. However, it does not directly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity on when to prefer this tool over others.

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

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

Annotations already declare readOnly, openWorld, idempotent hints. The description adds significant context: data comes from daily snapshots, bounded by 60-day TTL, provides time-series, trend classification, decay calculation from daily closes (not intraday), and response structure. No contradictions.

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

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

The description is a single block but well-structured: starts with core purpose, then details response fields (tracked[], expired[], snapshot_dates[]) with clear labels. While somewhat verbose, every sentence adds value. Could be slightly more concise, but overall effective.

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

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

With no output schema, the description fully explains all return fields (tracked, expired, snapshot_dates) and their subfields (trend, decay, first_seen, lifespan_days, etc.). Also covers limitations (60-day TTL, snapshot start, intraday vs. daily). Complete for a complex tool.

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

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

The input schema has 100% coverage with descriptions of both parameters (days, window). The description adds value by specifying default values (14, '1wk'), clamp range (2-30), and listing window family options ('24hr | 1wk | 1mo'), enhancing usability beyond the schema alone.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on persistence/decay telemetry rather than raw edges.

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

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

The description implies usage for assessing edge quality over time (e.g., distinguishing fresh vs. old wide edges) but does not explicitly state when to use or not use this tool versus alternatives like polymarket_edges. No clear 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description, which adds behavioral details like walking the ladder, returning verdict (clean|degraded|cannot_fill), and warning about forced directional risk. 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 and informative, but could benefit from better structure (e.g., bullet points for modes) to improve readability. However, every sentence is valuable and front-loaded with key purpose.

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

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

Despite no output schema, the description fully specifies return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and covers edge cases like thin_legs and forced_directional_risk. Complete for a risk-check tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema. For example, it explains size_usd in basket mode as 'settlement notional S — shares per leg' and clarifies default side logic for baskets. This enhances the schema's documentation.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, providing specific verb+resource and differentiating from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial basket fills converting an arb into unhedged directional position, indicating when not to use.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing behavioral traits: how compatibility_warning and compatibility_codes work, the meaning of each code, the fact that unknown metric types are never paired, the fee disclosure (gross not net), and the unverified pairing logic. It even explains that temporal_alignment null means 'could not be computed, not that they align'. This is comprehensive behavioral disclosure.

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 (~300 words) but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, etc.). It front-loads the core purpose and then systematically covers caveats and edge cases. While dense, every section contributes essential information for correct usage; the length is justified by the tool's complexity.

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

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

For a complex tool with no output schema, the description covers virtually all aspects an agent needs: mode selection, response structure, safety fields, code meanings, skipped classification logic, fee disclosure, and alignment semantics. It even anticipates user pitfalls (e.g., null temporal_alignment) and provides explicit warnings. 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% with each parameter described. The description adds valuable context beyond the raw schema by explaining the topic shortcuts list, the override semantics ('Overrides the topic-mapped Kalshi side'), and the relationship between topic and explicit parameters. It clarifies that both modes run the same matcher, which is not evident from the schema alone.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly states the tool compares two specific venues, and differentiates from sibling tools like polymarket_arbitrage by focusing on spread between venues rather than within-venue arbitrage. The two distinct modes (topic vs explicit ticker/slug) are clearly articulated.

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

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

The description explicitly advises when the spread is a real signal ('when the bet shapes are equivalent') and warns that when they aren't, the tool will disclose it. It also cautions that 'most pre-mapped topics return compatibility_warning today' and emphasizes 'pre-mapped ≠ tradeable', guiding agents to verify safety fields. It describes both modes and how they should be invoked, giving clear context and implicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: scoped to identifier (anonymous IP, BYO key hash, or account ID). 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?

Description is three sentences, front-loaded with the purpose, and every sentence adds value. No waste and clearly structured.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description fully covers functionality, use case, and scope. Nothing 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?

Input schema has 100% coverage for the single 'key' parameter. Description adds that omitting key lists all keys, which matches schema explanation. No additional depth needed, baseline 3 is appropriate.

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

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

Description clearly states verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings by mentioning 'remember' and 'forget'. It covers both functions of recalling a specific key or listing all keys.

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

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

Description provides explicit use case: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget. Missing explicit when-not-to-use, but the guidance is strong.

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, destructiveHint=false. Description adds that mark_read can flag events read, which is a state change but idempotent. Consistent with annotations; no new behavioral traits beyond what annotations imply.

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 main action and return details. No redundant text. Every sentence adds value.

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

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

No output schema, but description explains what each alert carries (source, citation_uri, raw payload). Covers all parameters except unread_only implicitly. Mentions polling and alternative HTTP endpoint. Could include response format details, but sufficient.

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

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

Schema coverage is 100%, but description adds value by explaining mark_read's effect (next call shows newer ones) and giving an example for type ('sec_8k'). 'unread_only' not explicitly described, but schema covers it. Baseline 3 plus extra for context on mark_read.

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?

Clear verb 'pull' and specific resource 'fired events from your subscription feed'. Distinguishes from sibling tools like list_subscriptions and subscribe by detailing what data is returned (source, citation_uri, raw payload).

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

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

Provides guidance on filtering by type and since, using mark_read to manage read state, and mentions polling suitability. Provides alternative HTTP endpoint for scripts/dashboards. Lacks explicit 'when not to use', but context is clear.

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

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

The description adds significant context beyond annotations, including fan-out to multiple sources, fallback logic, soft-fail for USPTO, and return structure (changes[] with URIs). No contradictions with annotations.

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

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

The description is well-structured and front-loaded but slightly lengthy due to detailed explanations of sources and fallback. It could be more concise while retaining 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 the complexity (multiple sources, fallback, soft-fail, three required parameters) and no output schema, the description covers all aspects: purpose, parameters, sources, fallback, return type, and alternatives without gaps.

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

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

The description adds practical guidance beyond the schema: type is limited to 'company', value accepts ticker or CIK, and since includes relative date shorthand with recommended typical values. Schema coverage is 100%.

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

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

The description clearly states the tool provides a change feed for a company in a recent time window, specifying sources (SEC, GDELT, USPTO) and distinguishing from the sibling entity_profile 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 provides example queries and explicitly recommends an alternative (entity_profile) when a static profile is needed. It also explains fallback behavior (GDELT to GNews) and soft-fails for USPTO.

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

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

Discloses important behaviors beyond annotations: memory is scoped by user identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations indicate idempotentHint=true, which description does not contradict.

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

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

Concise and well-structured: purpose statement, usage guidance, behavioral details, and pairing with other tools. No extraneous information.

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

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

Fully covers the tool's functionality for its complexity. With only two simple params and no output schema (write operation), the description provides all necessary context: when, what, how long stored.

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%. The description adds value by suggesting key naming conventions (e.g., 'subject_property', 'target_ticker'), which enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides specific examples (resolved ticker, target address, user preference, research subject) and distinguishes from siblings like recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget for retrieval and deletion, providing clear context for usage.

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 this as read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral detail: internal cascading lookups, graceful degradation if GLEIF or OpenFIGI is unavailable, explicit `unresolved` reporting, and candidate-returning behavior on ambiguous matches. No contradiction with 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 dense but front-loaded with the core directive ('Use FIRST whenever you have a name but need an ID') and supported types. It contains no filler, but the wall-of-text formatting with many parenthetical caveats makes it harder to scan than a structured layout with bullets would be.

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 carries the full burden of explaining return behavior, and it does: it names returned fields (CIK, ticker, LEI, FIGI, RxCUI), explains `figi_candidates` for ambiguity, documents `unresolved`, and covers source labels and degradation. Nothing an agent needs to understand the tool's results 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?

Although schema coverage is 100%, the description adds crucial meaning beyond the schema: it reveals that ISIN is accepted as input, explains that bond lookups must use the exact issuer name rather than the full noun phrase, and clarifies how multiple matches are presented. This materially improves correct invocation.

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 and resource: it resolves a user-spoken NAME to canonical/official identifiers required by other tools. It enumerates concrete query examples, supported entity types, and even explains what happens on ambiguous matches, making it easy to distinguish from siblings.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives query patterns for each supported type. It does not, however, name sibling tools to avoid or state explicit when-not-to-use conditions, so it falls just 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?

The description adds significant context beyond annotations: it explains the workflow (probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized), the return structure (ranked list with score, confidence, signal density), and the treatment of the first entity as the 'subject'. No contradictions with annotations.

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

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

Three sentences, front-loaded with the main purpose, no unnecessary words. Every sentence adds value.

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

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

Despite no output schema, the description clearly states what the tool returns (ranked list with score, confidence, signal density). For the given complexity and parameters, this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the entities array ordering (first is subject) and the default model, which goes beyond the schema.

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

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

The description uses specific verbs ('Compare', 'Probes', 'Ranks') and nouns ('AI visibility', 'entities'), clearly distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, but it does not explicitly state when to use this tool versus siblings like compare_entities.

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 behavior. The description adds valuable behavioral details: fans out across two services, potential 5-30s delay for Bundlephobia first measurement, partial failures degrade gracefully with sources_failed listed.

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

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

The description is concise with two well-structured sentences. It front-loads the key purpose and then provides necessary detail without redundancy.

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

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

Despite no output schema, the description fully explains the return format (summary block, advisory details, links, alternative versions) and behavior under partial failures. It also specifies ecosystem scope and graceful degradation.

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

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

Schema description coverage is 100%, so baseline is 3. The description enhances parameter understanding by explaining how the parameters are used (fans out to deps.dev and bundlephobia) and mentions the default behavior for version, which aligns with 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 does a composite check for npm packages, combining data from deps.dev and bundlephobia, using the verb 'scan' and resource 'dependency'. It distinguishes itself from sibling tools by specifying its unique functionality and 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 the tool (questions about safety, popularity, size, cost) and provides exclusion criteria (NPM ecosystem only in v1, other ecosystems handled differently).

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds crucial behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping), cosine similarity, and return structure (passages with offsets and scores). 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?

Four sentences, front-loaded with purpose. Each sentence adds unique value: purpose, use case, pairing, and technical details. No redundancy or 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?

Despite no output schema, the description explains return format (top-N passages with character offsets and similarity scores), limits (200K chars with truncation flag), and parameter constraints. All essential information is covered.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description reinforces usage but does not add significant new semantic meaning beyond what the input schema already provides.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides specific examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and the context of avoiding large prompts.

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 when the record is too big to cram into the prompt'. Also specifies what to pair with (ask_pipeworx_grounded) and the benefit of saving context and returning verifiable passages.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by specifying the source (EBI/NHGRI) and keyless access, as well as the specific fields returned (risk allele, p-value, etc.), providing behavioral context beyond annotations.

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

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

Single sentence that is front-loaded with the core purpose and key details. No redundant or unnecessary information; every phrase contributes to understanding.

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?

Tool has only two simple parameters, no output schema, and rich annotations covering safety and idempotency. The description sufficiently explains what the tool returns and its source, making it complete for an agent to use. Minor gap: no mention of pagination or error handling, but overall adequate.

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

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

Schema coverage is 100% with descriptions for both rsid and limit. The description does not add new parameter details beyond what the schema provides, so baseline score of 3 is appropriate. The description does mention rsID and limit implicitly but no extra semantics.

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

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

Description clearly states it retrieves trait/disease associations for a SNP from the GWAS Catalog, listing specific fields (risk allele, p-value, etc.) and the data source. It differentiates from siblings like get_snp and studies_by_trait by specifying the focus on associations with detailed effect sizes.

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

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

Description mentions 'Keyless, from EBI/NHGRI' and provides examples, but lacks explicit guidance on when to use versus alternatives like get_snp or studies_by_trait. No when-not or exclusionary context is provided.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying return fields (accession, PubMed ID, etc.), that it is keyless, and the data source (EBI/NHGRI). This goes beyond annotations but does not cover all edge cases (e.g., pagination).

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

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

Two sentences, front-loaded with the core purpose. Every sentence adds value: first for what it does, second for return fields and source. 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?

For a simple list-returning tool with good annotations and schema, the description is quite complete. It lists return fields, notes keyless access, and mentions the data source. The absence of pagination details is a minor gap, but overall adequate.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only noting that trait is an EFO term. The schema already provides examples and descriptions.

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

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

The description clearly states the tool finds genome-wide association studies for a specific disease/trait, using the GWAS Catalog. It distinguishes from sibling tools like 'get_snp' and 'snp_associations' by focusing on studies by trait, and the name itself reinforces the 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 clear context for when to use the tool (to find studies for a given trait), but does not explicitly state when not to use it or mention alternative tools. However, the context is sufficient for an AI agent to infer appropriate usage.

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

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

Annotations indicate idempotent, non-destructive, open-world. The description adds details: OAuth requirement, phone verification, SMS cap (10/day), webhook auto-disable after 10 failures, and that the webhook secret is returned only once. No contradiction with annotations.

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

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

The description is thorough but somewhat lengthy. It front-loads the primary purpose and then expands into details. Every sentence adds value, but minor redundancy could be trimmed (e.g., phone verification is mentioned twice).

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

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

Given the complexity (3 parameters, nested objects, 5 enum types, multiple delivery options) and no output schema, the description is comprehensive. It covers prerequisites, type-specific parameters, delivery channel behavior, limits, and return value (subscription id).

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 substantially enriches parameter meaning with examples (e.g., items codes for sec_8k, topics for polymarket_edge, required fields for patent_grant). Delivery channels are explained in detail beyond schema descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like 'unsubscribe' 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 specifies prerequisites (Pipeworx OAuth account), supported event types, and delivery channels. It also mentions that anonymous/BYO cannot persist subscriptions, giving a clear when-not-to-use. However, it does not directly compare to closely related tools like 'recent_alerts' or 'polymarket_arbitrage'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining the output structure (category-bucketed questions with tool+argument shapes) and that it draws from a live catalog, which goes beyond annotation scope.

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 synonyms and purpose, uses bullet-like structure for categories, and each sentence contributes value. Slightly verbose but well-organized; no wasted words.

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

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

For a tool with no output schema, the description fully describes the return value: category-bucketed example questions with tool details. It covers usage, parameter behavior, and the context of being an onboarding entry point, leaving no major gaps.

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

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

Schema coverage is 100%, and the description elaborates on the topic parameter: lists specific focus areas ('finance', 'pharma', etc.), explains that omitting gives a cross-category spread, and connects to the overall purpose.

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 category-bucketed example questions for onboarding new users, using specific verbs like 'returns' and 'call'. It distinguishes from siblings by being the first tool to use when learning about Pipeworx's capabilities.

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 to 'use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to focus with a topic parameter. This provides clear when-to-use guidance and contextual 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 annotations (readOnlyHint=false, destructiveHint=false), the description adds key behavioral details: the row is deactivated, not deleted, so historical events remain via recent_alerts. No contradiction with annotations.

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

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

Three concise sentences with no wasted words. Front-loaded with the main action, followed by constraints and side effects.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, deactivation behavior, and impact on historical data. It is fully complete.

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

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

Schema coverage is 100% with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantic meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool cancels a subscription by ID. The title 'Unsubscribe from Alerts' and verb 'Cancel' make the purpose explicit, and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use and when not. It does not mention alternatives but the context is clear.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description goes further by disclosing the verdict taxonomy, the auto-fallback routing between structured and grounded pipelines, the presence of verbatim evidence with pipeworx:// citations, and the warning that could_not_verify carries a verification_error and is not evidence. This adds significant behavior 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 long but well-structured: it starts with trigger phrases, then states purpose, then explains the two verification paths, followed by return contract and an IMPORTANT caller note. Every sentence adds operational detail, but it could be tightened slightly without losing substance. Still, it is far from rambling and is appropriately 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?

There is no output schema, so the description carries full responsibility for explaining outputs. It enumerates the six verdicts, states the returned fields (actual value, citation, reasoning), and clarifies failure semantics (could_not_verify vs unsupported). Combined with the parameter guidance and routing logic, this is a complete operational spec for 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% for both parameters, and the description adds substantial meaning beyond the schema. It explains that tolerance_pct overrides the wording-implied tolerance, specifies the 0.5–50 range, and recommends 1–2% for hallucination detection. It also gives concrete example claims to clarify the claim parameter. This is strong added semantic value.

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

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

The description opens with explicit natural-language triggers ("fact check", "verify the claim that…") and defines the tool as "natural-language claim verification against authoritative sources." It distinguishes from siblings by specifying a structured path for company-financial claims and a grounded pipeline for all other factual claims, and even notes it replaces 4–6 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 "Use whenever the agent needs to check whether something a user said is factually correct." It then details when the structured SEC EDGAR path applies versus the grounded pipeline, and provides critical interpretation guidance: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source covers it. This is clear, actionable usage guidance.

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