Gdc

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

Adds context beyond annotations: describes default free model, BYO key for Anthropic, return structure, and that it probes multiple models. No contradictions.

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

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

Two sentences, front-loaded with action, no wasted words. Every sentence earns its place.

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

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

Despite no output schema, description describes return format (per-model fields + combined view) and covers all parameters. Sufficient for agent use.

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?

With 100% schema coverage, description further explains entity, models list, _apiKey purpose (pass-through to Anthropic), and context disambiguation, adding value.

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

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

The description clearly states it probes LLMs for knowledge about an entity and returns a visibility score per model, distinguishing it from sibling tools like compare_entities or entity_profile by focusing on AI visibility auditing.

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?

States use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly list when not to use or directly compare to 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes to a network of thousands of tools, returns structured answers with citation URIs, works on every tier, and handles live news streams. No contradiction with annotations is present.

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

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

The description is well-structured with bolded directives, a domain list, examples, and a clear escalation path. Despite its length, every sentence contributes necessary information for a default entry-point tool. It is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and remains scannable.

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

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

The description covers the tool's core function, when to use it, when to escalate to grounded or deep research, the output format (structured answer with citations), and its broad applicability across domains. Since no output schema exists, the description appropriately explains the return value characteristics. This is complete for a complex, routing-focused 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 achieves 100% coverage for the required 'question' parameter and lists multiple aliases. The description goes a step further by providing concrete examples of appropriate queries ('current US unemployment rate', 'Apple's latest 10-K') and mentioning the natural-language style, which helps the agent frame inputs correctly.

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

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

The description clearly states the tool routes user questions to the appropriate source among 5,562 tools across 1,462 verified sources and returns a structured answer with stable pipeworx:// citation URIs. It also explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique purpose obvious.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific conditions for using ask_pipeworx_grounded (single answer, verbatim evidence, confidence) and deep_research (broad/multi-part questions). It also addresses breaking-news use cases, leaving no ambiguity about when to choose this tool over alternatives.

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

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

Annotations already disclose readOnly, idempotent, non-destructive, and open-world hints, so the description does not need to repeat those. It adds valuable context about the experimental nature, candidate routing tests, and the fact that it does not fall back to anything—it is a full router. This enriches the agent's understanding of expected behavior.

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

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

The description is compact and front-loaded, delivering the core identity in the first sentence, then usage, current state, and comparison in subsequent sentences. Each sentence earns its place without excessive verbosity, though it could be slightly tightened.

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 lack of an output schema, the description compensates by noting the response shape is identical to ask_pipeworx. It also explains the relationship to the stable router, current status (no active candidate), and confirms it is fully operational. This is sufficient for an agent to select and invoke it correctly, though more detail about response structure would be even better.

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 fully documents the `question` parameter and its aliases (q, text, input, query, prompt), giving 100% coverage. The description does not add new parameter semantics beyond saying 'same arguments' as ask_pipeworx, which is consistent with the schema. Thus it meets the baseline but does not go further.

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

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

The description clearly states it is a beta version of ask_pipeworx with the same universal routing function, and explicitly distinguishes it from the stable ask_pipeworx by noting experimental candidate routing improvements. It uses specific language about what it does and how it differs, so an agent can understand its purpose immediately.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies it is currently identical to ask_pipeworx, and results are compared against the stable router for evaluation. It does not explicitly state when *not* to use it or mention alternatives like ask_pipeworx_grounded, 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 read-only, open-world, idempotent, non-destructive. The description goes far beyond by detailing the refusal mechanism (refusal_reason enum), the strict answer extraction from tool results, the verbatim evidence return, and the extra LLM call cost. 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?

Although moderately long, every sentence provides unique value: summary, mechanism, output shape, refusal reasons, use cases, cost tradeoff. The structure is front-loaded with the core purpose and ends with actionable guidance, with no redundancy.

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

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

The description fully covers the high-stakes context: refusal conditions, output format for success and failure, cost implication, and comparison to sibling. Without an output schema, it compensates by explicitly listing return fields. This is complete for an agent to invoke and interpret responses.

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

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

Schema describes all 6 parameters as aliases for question with full coverage. The description adds minimal parameter-specific context (e.g., 'fills arguments') but mostly focuses on system behavior rather than parameter meaning. Baseline 3 applied due to high schema coverage.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' and explains its routing/extraction flow. It explicitly distinguishes itself from ask_pipeworx via the grounded extraction and refusal behavior, satisfying the sibling-differentiation criterion.

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

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

Provides explicit guidance: use when answers will be quoted/cited/acted on and when facts must not be invented, with concrete examples (financial, legal, medical, public statements). Also states 'prefer ask_pipeworx for casual lookups,' giving a clear alternative and when-not-to-use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: fan-out logic, resolver contract, parent event extractor, safety mechanisms, news fallback handling, wide-spread liquidity checks, and resolution-rule risk. This goes far beyond annotations with no contradiction.

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

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

The description is very long (about 600 words) but well-structured with CAPS headings and clear sections. It front-loads the main purpose and usage. While every sentence provides value, the verbosity could be reduced slightly for quicker consumption.

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

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

Given the tool's complexity (multiple data sources, resolution matching, safety, etc.), the description covers almost all aspects. It details response shapes, resolver contract, parent event extractor, news fields, and edge cases. No output schema exists, but the description compensates fully.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the market parameter's flexibility (slug, URL, question text) and the practical implications of depth and include_raw. It enriches the schema's meaning without needing to compensate for gaps.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies the resource, action, and input types (slug, URL, question text). This distinguishes it from sibling tools like ask_pipeworx or deep_research, which are more general.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It implies when to use by being Polymarket-specific, but lacks explicit 'when not to use' or direct alternatives. However, it is clear enough for an AI agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: pulls SEC EDGAR data for companies (with fiscal year handling), FAERS data for drugs, returns sorted results, includes citation 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?

Three dense sentences with user phrases front-loaded. Efficient but could be slightly more concise while retaining information. Every sentence 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?

Despite no output schema, the description explains what is returned: paired data, citation URIs, results sorted by primary metric. Covers both entity types comprehensively. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains that 'values' are tickers/CIKs for companies and drug names for drugs, and specifies the data pulled for each type. Provides useful context.

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 lists specific user phrases ('compare X and Y', 'X vs Y', etc.) and clearly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes from sequential single-pack lookups, making purpose unambiguous.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups' and claims it replaces 8-15 sequential lookups. However, it does not mention when NOT to use (e.g., when only one entity is needed). Still provides clear context for when to use.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context: account/pricing requirements, second-hop iteration by depth, gap and contradiction handling, citation URI resolvability, semantic excerpting, and expected latency (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is long but maintains a logical flow: access requirements → core purpose → output semantics → alternatives → depth behavior → timing. Every sentence adds unique information, though some depth-related behavior is repeated from the schema. It is appropriately front-loaded with account requirements and the key alternative, but slightly heavier than the minimum needed.

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 and only simple annotations, the description is remarkably complete. It defines the findings packet (verbatim evidence, confidence, source, fetched_at, citation), explains gaps[] and contradictions[], describes citation resolvability, and sets performance expectations. This fully covers all decision-relevant context.

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

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

Schema coverage is 100% and both depth and question already have descriptions. The description enhances this by explaining the practical consequences of depth levels (e.g., 'depth:"standard" re-angles unanswered gaps', 'thorough:... up to ~90s') and reinforces that broad questions are acceptable. This goes beyond the schema's literal parameter text, so a strong 4 is warranted.

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, specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources'. It explicitly distinguishes itself from sibling tools by stating 'this is NOT open-web search' and contrasts its multi-call decomposition behavior against ask_pipeworx, making the purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states that if you're not signed in, use ask_pipeworx instead, covering all major edge cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This describes output format and readiness beyond annotations, with no contradictions.

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

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

The description is well-structured: first sentence states purpose, second gives usage and domain list, third describes output, fourth gives behavioral instruction. It is slightly long (5 sentences) but each sentence adds value; no fluff. Front-loaded with key information.

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

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

Given the tool's complexity (6 parameters, many aliases, no output schema), the description is complete: it explains the discovery purpose, when to call it, what the output contains (schemas and examples), and how parameters work (aliases). Without an output schema, the description adequately covers return format.

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 adds meaning by explaining that multiple parameters (q, task, search, description) are aliases for 'query', and provides example queries and use cases. This clarifies the parameter semantics beyond the schema's individual 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's purpose: 'Find tools by describing the data or task.' It specifies the verb 'find', the resource 'tools', and the method ('by describing the data or task'). It also distinguishes from sibling tools by advising 'Call this FIRST when you have many tools available,' which sets it apart from specific search or research tools in the sibling list.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist for: [domains]' and 'Call this FIRST when you have many tools available.' It clearly indicates when to use but does not explicitly list alternative tools or when not to use it, though the context implies direct invocation when the tool is already known.

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 complemented by the description detailing the fan-out across multiple sources, specific return fields (CIK, recent_filings with URIs, fundamentals sorted, patents soft-failing, news fallback, LEI), and the sunset of USPTO PatentsView in May 2025. 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 dense with information and front-loaded with example queries. Every sentence serves a purpose, but it is slightly verbose due to listing all data sources and return fields. Could be tightened slightly without losing clarity, but overall well-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 complexity (multiple data sources, soft-failures, specific return fields), the description is remarkably complete. It covers all key aspects of what the tool does and returns, including limitations and fallback behaviors. No output schema exists, so the description adequately substitutes.

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?

Both parameters have full schema coverage (100%) and descriptions. The description adds value by providing concrete examples ('AAPL', '0000320193'), clarifying that 'type' only supports 'company', and reiterating that names are not accepted. This goes beyond the schema's minimal 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 returns a full cross-source profile of a US public company, with specific examples of user queries ('Tell me about X', 'research Acme') and lists the data sources consulted. It effectively distinguishes this tool from siblings like 'compare_entities' and 'resolve_entity' by emphasizing it should be preferred for holistic views.

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 ('ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view'), what inputs are accepted (ticker or CIK, not names), and directs users to 'resolve_entity' first if only a name is available. This provides clear guidance on alternatives and limitations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds behavioral context by specifying the reasons for deletion (stale context, task completion, sensitive data), going beyond the annotations without contradicting them.

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

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

The description is concise with two sentences, front-loading the core action and following with usage guidance. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers the purpose, usage guidelines, and pairing with siblings. It is complete for effective agent 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% and the schema already describes the single parameter 'key' as 'Memory key to delete'. The description does not add new parameter information beyond what the schema provides, so a 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 uses the specific verb 'delete' and identifies the resource as 'a previously stored memory by key'. It distinguishes the tool from its siblings 'remember' and 'recall' by mentioning them, making the tool's unique purpose 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 states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also pairs the tool with 'remember' and 'recall', guiding the agent on alternatives and complementary actions.

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. Description adds that it fetches the page and extracts data, which is consistent but does not add significant behavioral depth beyond annotations.

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

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

Two sentences, front-loaded with main purpose, then usage examples. Every sentence adds value with no redundancy.

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

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

Given the low complexity (2 params, no output schema), the description covers input, output format, and use cases. Annotations provide safety context. Nothing essential 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 both parameters described. Description adds 'Full URL' and 'default 25, max 50' but these are redundant with schema descriptions. 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?

The description uses a specific verb ('generate') and resource ('llms.txt file') and clearly states the purpose: making a site indexable by AI crawlers. It distinguishes from sibling tools by focusing on a specific output format.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. 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?

Annotations already declare idempotent, read-only, non-destructive. The description adds that it returns summary counts and notes 'keyless, open-access metadata,' which is useful behavioral context.

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

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

Two straightforward sentences, front-loaded with core action. 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 a simple lookup with one parameter, rich annotations, and no output schema, the description adequately explains return values (details plus summary counts) and access requirements.

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

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

Schema coverage is 100% with a clear parameter description and examples. The description repeats the purpose but does not add new 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?

The description clearly states the tool looks up a single NCI GDC project by project_id and returns details plus summary counts. It gives a concrete example (TCGA-BRCA) and distinguishes from list_projects by focusing on single project lookup.

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

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

The description implicitly indicates use for single project lookups but does not explicitly state when not to use or name alternatives like list_projects. However, the context of sibling tools makes it clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying that results are 'ranked by case count' and that it is 'open-access', which are behavioral traits not covered by structured annotations.

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

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

The description is concise, consisting of two sentences with no extra words. It efficiently communicates purpose, context, and return fields, making it easy for an agent to parse.

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

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

Given the tool's simplicity (list with pagination) and the richness of annotations and schema, the description provides all necessary context: what the tool lists, what fields it returns, and its open-access nature. No further details are needed.

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 full coverage of the two parameters ('from' and 'size') with descriptions. The description does not add additional parameter-specific information beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('List'), the resource ('NCI Genomic Data Commons cancer-genomics projects'), and specific context (e.g., 'TCGA, TARGET, CPTAC') and ranking ('by case count'). It also lists the fields returned, making the tool's purpose unambiguous and distinct from siblings.

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

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

The description implies usage for listing open-access projects but does not explicitly state when to use this tool versus alternatives like 'get_project' or 'search_cases'. The phrase 'keyless, open-access metadata' hints at no authentication requirements, but explicit guidance is lacking.

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=true, destructiveHint=false, idempotentHint=true. The description adds context about returning only active subscriptions by default and the optional include_inactive parameter, which is sufficient.

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

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

The description is two sentences, no wasted words. First sentence states purpose and return fields, second gives usage guidance. Perfectly concise and 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?

Given the tool's simplicity, the description covers purpose, return fields, and usage context. Annotations handle safety. No output schema but return fields are listed. Complete for a list tool.

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

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

Schema coverage is 100% with a single parameter, include_inactive, already described in the schema. The description does not add additional meaning beyond the schema, 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 'List the caller's active subscriptions', specifying the verb and resource. It also lists the return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use the tool relative to subscribing and unsubscribing.

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 (all false), the description discloses key behaviors: the claim_token workflow for tracking, rate limiting ('Rate-limited to 5 per identifier per day'), no cost ('doesn't count against your tool-call quota'), and daily digest review. This is meaningful context that annotations alone don't convey.

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

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

The description is dense but every sentence carries distinct information. It opens with purpose, then quickly moves to usage rules, exclusions, and the token workflow. Slightly long, but appropriate given the tool's multi-step workflow and constraints.

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 covers the essential return concept (claim_token), the later lookup behavior, the scope of valid feedback, and the rate limit. The input schema fully documents all 4 optional parameters. The combination gives a complete picture 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 coverage is 100%, so baseline is 3. The description adds semantics by explaining how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), instructing that messages must reference Pipeworx tools/packs, and mapping `type` values to scenarios. This adds value beyond the schema, though the schema already does a strong job.

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, specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates concrete use cases (bug, feature/data_gap, praise). It differentiates from sibling tools by establishing this as the feedback channel for Pipeworx-specific tools, not research or project 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?

It explicitly states when to use (bugs, missing features, praise) and when not to use ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). Also gives fallback guidance ('Not sure? Pipeworx tool names are the ones this connection lists').

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, and destructiveHint=false. The description adds valuable context: self-aggregating from CF analytics, no PII, and caching behavior (5min-1h). This exceeds the baseline set by annotations.

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

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

The description is extremely concise: two sentences plus a bullet-style list of use cases. The main purpose is front-loaded in the first sentence. Every sentence adds value; no fluff or redundancy.

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

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

Given the tool's low complexity (one optional parameter, no output schema) and rich annotations, the description covers all necessary aspects: purpose, usage, parameter context, data source, caching, and privacy. It is fully complete for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds meaning by linking different windows to specific use cases ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which enriches the schema definition.

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

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

The description uses a specific verb ('returns') and clearly identifies the resource ('top tools, top packs, total call volume'). It also lists three distinct use cases that implicitly differentiate it from sibling tools like 'discover_tools' by focusing on trending/current usage rather than general discovery.

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 'Useful for:' followed by three concrete scenarios, giving clear guidance on when to use the tool. However, it does not provide direct exclusions or contrast with alternatives among siblings, which would elevate it to a 5.

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

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

Annotations indicate readOnlyHint and idempotentHint, consistent with description. Description adds critical behavioral details: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live book depth, 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 densely packed with useful information, front-loaded with main purpose and modes, and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Slightly verbose but every sentence adds value, earning a 4.

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

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

Despite no output schema, the description explains the response structure in detail (opportunities[], partition_check, fill_check fields). It covers edge cases like low similarity rejection, partition filter, and fill check results, making it complete for an advisory 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% (both parameters described), but the description adds significant meaning: the event parameter accepts full URLs and slugs, the topic parameter uses seed questions, and explains how each mode operates. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with specific modes (no args, event, topic) and explains each. It distinguishes itself from sibling tools by detailing its 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?

The description explicitly guides when to use each mode: trending scan with no args, single-event with event slug, cross-event with topic. It also warns against trading when fill_check shows unrealizable edges and references 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: caching at the KV level (1h), detailed model families per segment, tradeable-edge knobs, and diagnostics for understanding empty segments. This greatly exceeds what annotations provide without contradiction.

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

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

The description is well-structured with clear headers and bullet points, but it is verbose. Every section adds value, but conciseness could be improved by trimming redundant details.

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

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

Given the tool's complexity (9 parameters, three segments, no output schema), the description is highly complete. It covers return structure, diagnostics, caching, and parameter interactions, ensuring an agent can invoke it correctly.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description complements the schema by explaining context and usage of knobs (e.g., slippage_pp, min_partition_leg_kelly), adding meaning 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets) and the action (scan and return opportunities), distinguishing itself from siblings by referencing Pipeworx data and detailing three unique segments.

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 frames the usage: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs and diagnostics to help interpret empty results. However, it lacks explicit when-not-to-use guidance or comparison to sibling tools like 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: it reads from daily snapshots, provides trend/decay metrics, and notes data gaps and TTL bounds. 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: purpose first, then args, then detailed response fields, then limits. Each sentence is informative, though slightly verbose. It front-loads the core question, making it efficient for agent scanning.

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

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

Despite no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), data types, and limits. It covers all necessary context for a low-complexity tool with two optional parameters, leaving no ambiguity.

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

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

Schema coverage is 100% with parameter descriptions. The description adds default values and extra context (e.g., 'snapshot family' for window, clamp range for days), enriching the schema without redundancy. Baseline is 3 due to high coverage, but the added defaults and response explanation justify a 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's purpose: 'Answers how long has this edge existed and is it shrinking?' It specifies verb (track), resource (edge persistence from polymarket_edges snapshots), and distinguishes from sibling polymarket_edges by focusing on time-series and decay. The example of a fresh vs. 3-week-old edge reinforces its unique value.

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 context on when to use ('fresh wide edge vs. stale edge') and includes interpretation guidance. However, it does not explicitly state when not to use this tool or directly compare it to alternatives like polymarket_edges, though the distinction is implied. Limits are clearly stated.

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?

Describes all returned fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and risks (thin books, unhedged directional position). Consistent with readOnly and idempotent 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?

Front-loaded with purpose and requirement, but somewhat dense in later paragraphs. Could use bullet points for return fields, but still reasonably concise given 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?

Comprehensive coverage of both modes, all return fields, and failure modes (cannot_fill, forced directional risk). No output schema, so description carries full burden and succeeds.

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?

Adds significant meaning beyond schema: explains default size_usd, default side for basket mode, and how size_usd is interpreted (spend vs target proceeds for single-market, settlement notional for basket). Schema coverage is 100% but description enriches it.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinguishes single-market and basket modes with specific verb+resource for each.

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

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

Explicitly requires one of `market` or `event`, describes when to use each mode, and advises using this tool before acting on arb signals or trades above ~$500, including warnings about partial fills.

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, idempotentHint, and destructiveHint false. The description goes far beyond by detailing the response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases like bet shape mismatches. It clearly explains when spreads are meaningful and when they are not.

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 long. However, it is well-structured: front-loads purpose, then modes, response, safety fields, and caveats. Every sentence adds value, though minor trimming could improve conciseness without losing meaning.

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

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

Given there is no output schema, the description fully explains the response structure (leg-by-leg prices, matched spread, top_spreads_pp, safety fields). It covers temporal alignment, bet shape equivalence, and edge cases like skipped comparisons. For a complex tool with 3 parameters, this is exceptionally complete.

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

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

Schema coverage is 100%. The description adds significant meaning: it lists the 10 pre-mapped topic shortcuts, explains that explicit parameters override the topic-mapped side, and clarifies the logical relationship between parameters (one mode requires topic, the other both explicit params). This adds context beyond the schema definitions.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairings) and explicitly differentiates from sibling tools by focusing on cross-venue comparison. The verb 'compute' is implied and the resource 'spread' is 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 explains two usage modes and provides guidance on when spreads are valid via safety fields (compatibility_warning, temporal_alignment). It warns that most pre-mapped topics return compatibility warnings, so spreads are rare. However, it does not explicitly compare to sibling tools like 'polymarket_arbitrage', though the cross-venue focus 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description is not required to cover safety. The description adds useful context about scoping ('Scoped to your identifier') and pairing with remember/forget, but does not disclose additional behavioral traits 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 two sentences long, front-loads the core action, and includes all essential information without redundancy. 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers both usage scenarios (retrieve by key, list all keys) and provides necessary context about scoping and pairing with sibling tools.

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 description explaining the 'key' parameter. The description adds meaning by explicitly stating that omitting the key lists all saved keys, which is valuable context not fully captured in the schema's brief description.

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

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

The description clearly states the verb 'retrieve' and the resource 'value saved via remember', and distinguishes it from siblings (remember, forget). It also specifies the behavior when omitting the key parameter (listing all keys), making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool: 'look up context the agent stored earlier ... without re-deriving it from scratch'. It also implies when to omit the key to list all saved keys, though it does not explicitly state when not to use it or mention alternatives beyond the sibling tools.

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

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

Annotations indicate read-only, open-world, idempotent, not destructive. Description adds side effect of mark_read and that dates are ISO timestamps. Does not contradict annotations and adds useful behavioral context.

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

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

Four sentences with no wasted words. Front-loaded purpose, then details. Efficient and readable.

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

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

Tool has no output schema, but description explains return fields (source, citation_uri, payload). Also mentions compatibility with polling and HTTP endpoint. Could note pagination or ordering, but adequate given simplicity.

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

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

Description adds meaning beyond schema: explains 'since' as ISO timestamp, 'mark_read:true' flags events to avoid repeats, and gives example type 'sec_8k'. Schema descriptions are generic; description provides usage context.

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 pulls fired events from subscription feed and returns recent alerts with specific fields. It stands out from siblings by focusing on alerts feed, not search or analysis.

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

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

Provides guidance on filtering by type and since, setting mark_read, and notes polling works fine. Also mentions an alternative HTTP endpoint. No explicit when-not-to-use, but sufficient context.

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

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

Description discloses fan-out to multiple sources, fallback logic, soft-fail for USPTO, and parameter format. Annotations already mark it as read-only and idempotent; description adds behavioral nuances without contradiction.

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

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

The description is a single, dense paragraph front-loaded with example queries. Every sentence adds value—purpose, sources, parameters, output format, and sibling distinction—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 mentions return format (structured changes by source, total_changes, citation URIs). It covers all aspects: input parameters, source behavior, fallback, and distinctions from siblings, making it fully complete for a tool of this complexity.

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

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

Although schema coverage is 100%, the description significantly enriches parameter semantics with examples (e.g., '7d', '30d', '3m', '1y' for since; ticker vs CIK for value). It explains constraints and usage beyond what the schema 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 explicitly states the tool provides a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and giving example queries. It distinguishes from sibling tool entity_profile, making its purpose very 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 provides explicit when-to-use scenarios (e.g., 'What's new with X') and when-not-to-use (e.g., 'Use entity_profile instead when you want the static profile'). It also explains fallback behavior between GDELT and GNews, aiding correct invocation.

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 idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: storage is key-value scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This covers retention behavior 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?

Three sentences with no redundant words. The first sentence presents the core purpose, followed by usage guidance and behavioral notes. Every sentence adds value.

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

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

For a simple key-value store with no output schema, the description fully covers: what to store, when to use, retention rules, and pairing with recall/forget. No gaps.

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

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

Schema has 100% coverage with clear descriptions for both key and value. The description adds context about key-value pairs being scoped by identifier but does not add significant meaning beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to save data for reuse across conversations. It provides concrete examples (resolved ticker, target address) and contrasts with sibling tools recall and forget, establishing a distinct 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?

The description explicitly advises when to use the tool ('when you discover something worth carrying forward') and references sibling tools for retrieval and deletion. It does not explicitly state when not to use it, but the guidance is clear enough for most scenarios.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds rich behavioral details: graceful degradation if GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers under an `unresolved` field, source labeling for each identifier, and internal cascading across endpoints. This surpasses the minimum needed for safe usage.

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 information-dense, with no filler. It opens with relatable examples, then states purpose and supported types. The length is justified by the need to explain multiple identifier sources and fallback behavior, but it lacks visual structure (e.g., bullets) and could be slightly streamlined without losing value.

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

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

With no output schema, the description carries the burden of explaining return semantics. It does so thoroughly: it lists the identifiers returned for company/drug, mentions source labeling, the `unresolved` section, the drug citation URL, and fallback behavior. This gives an agent sufficient understanding of what to expect and how to handle partial results.

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

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

Schema description coverage is 100% with meaningful descriptions for type and value. The tool description supplements this by detailing input formats for each type (e.g., ticker, CIK, ISIN, brand/generic), the ISIN-to-LEI mapping behavior, and the distinction between company and drug. This adds context beyond the raw schema, justifying a score above baseline.

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

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

The description leads with concrete user queries ('What's the ticker for…') and states its core function: resolving user-spoken names to canonical identifiers. It mentions specific supported types (company, drug) and explicitly frames itself as the first step when you have a name but need an ID, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' with examples of relevant user intents. It also explains how it replaces 2-3 manual lookups, giving the agent clear context for when to select this tool. While it doesn't list exclusions, the 'first' guidance implies precedence over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This 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?

The description is two sentences plus a return summary, front-loading the core purpose. It is efficient and well-structured, with no wasted words.

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

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

With 4 parameters all documented in the schema, the description explains the output format (ranked list with score, confidence, signal density). It could mention array size constraints or error conditions, but overall it's complete enough for the complexity.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning: the first entity is treated as 'subject' for narrative, context disambiguates common names, and models parameter explains supported values and API key requirement. This provides context beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 explicitly says it is useful for competitive AI-marketing audits and provides an example query. It implies when to use (comparing multiple brands) and implicitly distinguishes from single-entity tools, but does not explicitly state when not to use or provide 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 (readOnly, idempotent, etc.), description details latency (5-30s on first bundlephobia measurement), graceful partial failure with 'sources_failed' list, and multi-source fan-out behavior. 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 sentences pack purpose, usage, and behavioral details front-loaded. No extraneous words; every sentence earns its place.

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

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

Despite no output schema, the description enumerates return fields (summary block, advisories, links, versions) and covers failure modes. For a simple two-parameter tool, this is comprehensive.

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

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

With 100% schema coverage, baseline is 3. Description adds value by confirming scoped packages are accepted ('@types/node') and explaining default version behavior (latest if omitted), which goes beyond the schema descriptions.

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

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

Description clearly states verb ('check'), resource ('npm package'), and overall purpose ('composite should I add this package check'). Distinguishes from siblings by being a specialized dependency scanning tool; no other sibling covers this domain.

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

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

Explicit usage scenarios provided ('when agent asks is X safe/popular/small') and ecosystem limitation stated ('NPM only; other ecosystems fall under deps.dev directly'). Lacks explicit naming of alternative tools but clearly directs to deps.dev for non-NPM.

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 openWorldHint, so the safety profile is clear. The description adds value by listing the returned fields (case_id, submitter_id, primary site, etc.) and specifying it is 'Keyless, open-access metadata', which goes beyond annotations. 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 extremely concise (two sentences), front-loading the core action and resource, then listing key return fields and access notes. 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?

The description covers the tool's purpose, filters, and return fields. However, it omits mention of the 'size' parameter for pagination, which is documented in the schema but not in the description. Given no output schema, the return field list is helpful, but a mention of pagination would improve completeness.

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

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

Schema coverage is 100% with clear parameter descriptions. The description mentions primary_site and project_id as filters, but adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it searches NCI GDC cancer cases (patients/samples) by primary site and/or project. It specifies the resource (cases) and the filtering criteria, distinguishing it from sibling tools like 'search_files' which target files.

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 indicates this tool is for searching metadata by primary site and/or project, but does not provide explicit guidance on when to use it versus alternatives (e.g., 'search_files'). The 'Keyless, open-access metadata' note hints at the access context but lacks explicit 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?

The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only, idempotent operation. The description adds valuable context by stating 'Keyless, open-access metadata,' which clarifies authentication requirements and access level. 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 extremely concise at two sentences. The first sentence front-loads the core purpose and parameters, the second lists output and key context. Every sentence is essential and no redundant information.

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

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

Given the tool's simplicity (3 parameters, all documented), no output schema, and comprehensive annotations, the description covers all necessary information: what it does, how to use it (via examples), what it returns, and access context. No gaps are present.

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

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

The input schema provides full descriptions for all three parameters (100% coverage). The description adds value by giving concrete examples of valid values (e.g., 'TCGA-BRCA', 'Transcriptome Profiling') and listing returned fields, which helps the agent understand parameter usage beyond schema types.

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

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

The description clearly states the action (Search), the resource (NCI GDC genomic data files), and the available filters (project and data category). It also lists the returned fields, making the tool's purpose unambiguous. This distinguishes it from siblings like 'search_cases' which search different entities.

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

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

The description implies usage for searching files by project or data category, and provides example categories. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Usage guidance is implied but not explicit, which is adequate for a simple search tool.

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

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

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K with truncation and flag), and output details (offsets and scores). Annotations already indicate safety, but description adds rich behavioral context well beyond the structured fields.

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, well-structured with clear sections. Every sentence adds value: usage guidance, technical details, pairing recommendation. No redundant or vague phrasing.

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

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

Given no output schema, the description explains output format (passages, offsets, similarity scores) and cap/truncation behavior. Lacks mention of what happens with zero matches, but overall sufficient for a search tool with good parameter coverage.

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%, baseline 3. Description adds useful examples for text and query parameters beyond schema descriptions, and clarifies the meaning of limit as 'top-N' even though schema already mentions default. Additional context is helpful but not transformative.

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

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

Clearly states semantic search inside a fetched record with specific examples (SEC 10-K, article). Verb+resource+scope is precise, and the pairing with ask_pipeworx_grounded distinguishes it from siblings.

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

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

Explicitly says when to use: when the record is too big for the prompt. Provides context on saving context and pairing with another tool, but lacks explicit when-not-to-use or alternative tools beyond the pairing.

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 idempotentHint=true and readOnlyHint=false. The description adds context about account requirements, delivery rate limits, webhook secret one-time retrieval, and auto-disable after 10 failures. It does not contradict annotations.

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

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

The description is front-loaded with the core action and return value, followed by structured details on types and delivery. While slightly long, every sentence adds value. Could be tightened, but remains effective.

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

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

Given the complexity (3 params, no output schema), the description covers input specifications, side effects (persistent subscription, delivery behavior), return value, and prerequisites. It is comprehensive for a subscription creation 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 concrete examples for each type (sec_8k, polymarket_edge, etc.) and delivery channel constraints (phone verification, webhook signing). This significantly aids correct 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 creates a proactive monitoring subscription and returns the subscription id. It lists supported types and delivery channels, distinguishing it from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 when to use (to create subscriptions) and prerequisites (Pipeworx OAuth account). It includes constraints like SMS cap and webhook verification, but lacks explicit guidance on when not to use or alternatives for specific scenarios.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds behavioral context: it returns a set of example questions with tool/argument shapes, is safe to call without arguments, and serves as an onboarding assistant. No contradictions.

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

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

The description is well-structured with a list of categories and front-loaded usage guidance. It is slightly verbose but every sentence adds value. Could be slightly more concise, but still effective.

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

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

Given the tool's onboarding purpose, the description fully covers what it does (returns categorized example questions), when to use (first interaction), and how to use (optional topic). No output schema exists, but the description adequately describes the return content. Complete for its role.

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 (one optional topic with description). The description adds extra context by listing example values for topic and explaining that omitting it returns a full spread. This adds value beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions with exact tool calls. It effectively distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by specifying it should be used first to learn what Pipeworx can do.

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 FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains the optional topic parameter to focus on specific areas, and the default behavior when omitted.

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

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

Adds value beyond annotations: ownership enforcement, deactivation vs deletion, historical event persistence. No contradiction with annotations.

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

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

Two sentences, all essential info, no waste. Purpose and constraints stated upfront.

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

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

For a simple one-param tool, covers ownership, state change, and historical data. No output schema needed.

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 100%, so baseline 3. Description does not add new parameter info beyond schema's 'Subscription id (uuid) returned by subscribe'.

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

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

Clearly states verb 'cancel' and resource 'subscription by id'. Distinguishes from siblings 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?

Specifies ownership enforcement (only self-subscriptions) and effect (deactivation, not deletion) with reference to recent_alerts. Lacks explicit when-not-to-use but clear enough for typical 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?

The description richly discloses behavior beyond annotations: it explains the two pipeline paths, the meaning of special verdicts ('could_not_verify' means the check didn't happen and must not be interpreted as evidence; 'unsupported' means no source covers it), and the inclusion of citations and reasoning in the return. It also details error handling with verification_error{stage,detail}. This is exactly the context an agent needs and goes well beyond the basic readOnlyHint/openWorldHint 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?

Although the description is long, every sentence earns its place: it opens with trigger examples to aid natural-language recognition, then explains the two execution paths, return values, special verdict semantics, and the efficiency gain. The structure is logical and front-loaded, moving from general purpose to specific caller-facing warnings. No fluff or redundancy.

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

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

The tool has no output schema, so the description carries full responsibility for explaining return values. It covers all expected outputs: the six possible verdicts, the actual value with pipeworx:// citation, reasoning, and error details. For a high-complexity tool with two distinct pipelines and nuanced verdict meanings, the description is comprehensive. The context signals (2 params, no enums, no output schema) are fully addressed.

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 well-described parameters: 'claim' and 'tolerance_pct' are both documented with examples and semantics. The description adds some context (e.g., tolerance_pct used for hallucination detection, default implied by wording) but does not materially extend the schema's already thorough descriptions. Baseline 3 applies because the schema does the heavy lifting; the description doesn't compensate with extra details.

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

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

The description clearly states the tool's function as 'natural-language claim verification against authoritative sources' with specific verbs and resource. It distinguishes itself from sibling tools by focusing on claim verification and by describing the dual-path handling for financial vs. other claims. The example user phrases ('Is it true that…', 'fact check', etc.) leave no ambiguity about the tool's 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and details the two execution paths (SEC EDGAR fast path for financial, grounded pipeline for other facts). It also notes it replaces 4–6 sequential calls, giving a clear efficiency-based reason to choose this tool over alternatives. Though it doesn't name a specific alternative, the guidance is unambiguous.

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