Gdc

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description adds value beyond flags. It explains default model selection, API key usage for Anthropic, and the scoring approach, which are critical behavioral traits not captured in annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core action, then details model options, return format, and usage scenarios. No redundant sentences; 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 lacking an output schema, the description clearly outlines the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers the free vs paid model distinction and typical use cases. For a probe tool with moderate complexity, this is sufficiently complete.

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

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

Schema coverage is 100%, so each parameter has schema descriptions. The tool description adds context by clarifying the default model for 'models' and the role of '_apiKey' as a BYO key for Anthropic, and gives examples for 'entity'. This enriches understanding beyond the schema alone.

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

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

The description clearly states that the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the resource (business/brand/product/topic) and action (probe and score). Among sibling tools like 'scan_competitor_ai_presence', this tool's focus on a single entity and visibility scoring 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 provides concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), which helps agents decide when to invoke it. However, it does not explicitly exclude scenarios or compare to alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about routing to 3,689 tools and returning structured answers with citation URIs, but doesn't cover failure modes or edge cases.

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

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

The description is front-loaded with the key message and uses examples effectively, but is somewhat verbose. It could be tightened without losing essential guidance.

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

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

Given the tool's complexity (6 params, 1 required, no output schema), the description provides sufficient context for selection and invocation. It explains the routing mechanism and output format, though it omits error handling or limitations.

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

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

Schema coverage is 100% with all six parameters clearly described, including aliases. The description adds no additional nuance beyond the schema, so it meets the baseline without providing extra 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 the tool's purpose: it routes factual questions to a vast set of verified sources for authoritative structured data. It specifically lists many data domains and provides example questions, effectively distinguishing itself from web search.

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 'PREFER OVER WEB SEARCH' and gives detailed guidance on when to use, including specific query types and examples. It even suggests using it even if web search could answer, providing clear prioritization.

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 as true/true/true/false. The description adds behavioral details: the tool costs an extra LLM call, the same routing as ask_pipeworx, and explicit refusal reasons (not_in_source, no_tool_match, etc.). 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 somewhat lengthy, with repetition of the refusal reasons and output structure. While the front-loaded sentences convey purpose and usage, there is room for trimming redundant details without losing clarity.

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

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

Given the tool's complexity (3,689 sources, 867 sources) and lack of output schema, the description covers key aspects: purpose, behavior, output format (including fields like answer, evidence, confidence, source, fetched_at, refusal_reason), cost tradeoff, and refusal scenarios. It is sufficiently complete for an agent to understand its capabilities and limitations.

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

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

Schema coverage is 100% with all parameters documented. The description adds minimal value beyond the schema, mainly restating that the tool accepts a natural language question and listing the aliases. The schema already describes each alias. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's specific purpose: a hallucination-resistant mode for high-stakes reads that extracts answers only from tool results. It distinguishes itself from the sibling tool 'ask_pipeworx' by noting the additional cost and the explicit refusal mechanism.

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 on when to use this tool (when answers will be quoted, cited, or acted on, and the agent must not invent facts) and when to prefer the sibling 'ask_pipeworx' (casual lookups). It also lists typical use cases like financial verdicts, legal claims, etc.

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

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

Annotations indicate readOnly, openWorld, idempotent, and nondestructive behavior. The description adds extensive behavioral details: resolution process, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields with fallback handling, safety conditions for low-confidence matches and closed markets. 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 long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that front-load key information. Every sentence adds value, though the length may be slightly overwhelming. The structure aids readability for an AI agent.

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 (no output schema, internal components like classifiers and fan-out logic), the description is remarkably complete. It covers resolution, safety, response structure, edge cases (closed markets, wide spreads), and fallback mechanisms. Without an output schema, it thoroughly describes return values and fields.

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?

All three parameters (market, depth, include_raw) are fully described in the schema (100% coverage). The description adds significant meaning beyond the schema: explains that market can be a slug, URL, or text; clarifies depth options (quick vs thorough) and their impact; details how include_raw controls response size. This exceeds baseline expectations.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, and fanning out to category-specific data packs. It distinguishes itself from sibling tools by focusing specifically on Polymarket bets and providing a comprehensive research workflow.

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

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

Explicitly says "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." Provides concrete examples of queries. While it doesn't explicitly state when not to use it, the context of Polymarket betting is clear, and the description is detailed enough to guide appropriate usage.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds detail on data sources (SEC EDGAR, FAERS), fiscal year handling, and return format with citation URIs, which goes beyond annotations.

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

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

Description is fairly long but each sentence adds value. It is front-loaded with trigger phrases. Minor redundancy could be trimmed, but overall efficient.

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

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

Despite no output schema, description explains return format (paired data + citation URIs) and specifics per entity type. Covers data sources, edge cases (off-calendar fiscal years), and sorting behavior. Complete for this tool.

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

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

Schema has 100% coverage with descriptions and enum. Description adds meaning by specifying what metrics are pulled for each type (e.g., revenue, net income for companies; adverse-event counts for drugs) and that results are sorted by primary metric.

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

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

Description clearly states it does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases. It distinguishes from sequential single-pack lookups, which is a sibling alternative.

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 (comparison queries) and to prefer over sequential lookups. Provides context on handling fiscal year differences, but does not list exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations without contradiction.

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

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

The description is about 5 sentences, front-loaded with the core purpose, and efficiently covers usage domains and return format. It is concise with no superfluous text, though slight tightening would be possible.

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 adequately explains what the tool returns (top-N tools with schemas and examples) and the default/limit. It provides sufficient context for an agent to understand the tool's output and when to call it. Minor gap: no mention of error handling or edge cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions aliases for the query parameter and provides examples, but these are already present in the schema. The description does not add significant new meaning beyond what the schema already documents.

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 ('find tools by describing the data or task') and lists numerous domains (SEC filings, FDA drugs, etc.), clearly distinguishing it from sibling tools that perform specific actions. The tool is positioned as a discovery gateway, not a single-purpose tool.

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides strong guidance on when to use it, but does not explicitly list when not to use or name alternative tools, leaving some ambiguity.

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, non-destructive), description discloses detailed behavior: fans out over SEC EDGAR, XBRL, USPTO, news, GLEIF; lists exact return fields; notes USPTO API sunset and soft-fail; mentions fallback chain. This goes well beyond what annotations provide.

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

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

Description is detailed but well-structured, starting with example queries and progressively adding technical details. Every sentence adds value, though it could be slightly trimmed without losing key information. It efficiently communicates the tool's purpose and behavior.

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 comprehensively explains all return components (cik, company_name, recent_filings with URIs, fundamentals, patents with caveat, news with fallback, LEI). Also covers input constraints and source details, making it complete for an agent to use effectively.

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. Description adds value by providing examples of valid inputs ('AAPL' or zero-padded CIK '0000320193'), clarifying that names are not supported, and reiterating the enum constraint. This adds meaning 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 explicitly states it provides a full cross-source profile of a US public company in one call, using examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings by advising use of resolve_entity for names and preferring this over chaining single-source lookups.

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

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

Clearly states when to use this tool: for holistic views of US public companies, and to prefer it over chaining individual lookups. Also specifies when not to use it: for names only (use resolve_entity first). Provides explicit 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 indicate destructiveHint=true and idempotentHint=true. The description adds context (sensitive data, clearing saved info) beyond annotations but does not contradict 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?

Two sentences with no wasted words. The action is stated first ('Delete a previously stored memory by key'), making it efficient 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?

For a simple tool with one parameter, no output schema, and complete annotations, the description fully equips an agent to use it correctly, including guidance on when and with which 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% and the one parameter 'key' is described as 'Memory key to delete.' The description adds no further semantics beyond what the schema provides, meeting the 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 clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). It distinguishes from siblings by naming 'remember' and 'recall.'

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

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

Provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with 'remember and recall,' giving clear when-to-use and alternatives.

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

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

Annotations already indicate the tool is read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value without contradicting annotations.

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

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

The description is three sentences long, each serving a clear purpose: purpose/benefit, process, and use cases. It is front-loaded with the main action and avoids 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?

For a straightforward read-only tool with no output schema, the description covers purpose, process, output format, and use cases. With comprehensive annotations, no gaps remain.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully. The description does not add extra meaning or restrictions beyond what is in the schema, thus baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and target. It distinguishes from sibling tools by focusing on generating the standard file format for AI crawlers, which is unique compared to siblings like ai_visibility_check or scan_competitor_ai_presence.

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 lists three specific use cases (getting a client's site indexed, drafting for own project, auditing competitor's AI view), which provides clear context. It does not explicitly state when not to use or name alternative tools, but the use cases implicitly guide appropriate usage.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds valuable context: 'Keyless, open-access' and specific return fields ('case_count, file_count'). 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?

Single sentence, no filler, front-loaded with the core action and resource. Every word is meaningful.

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 keyless lookup with one parameter and no output schema, the description adequately states what it returns (details + summary counts). Missing error handling info, but not critical.

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

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

Schema covers 100% of parameters with a description for project_id. The description reinforces examples and adds no new semantic detail but reinforces usage, earning a slight bonus over baseline 3.

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

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

The description specifies the exact verb ('look up'), resource ('single NCI GDC project'), unique identifier ('project_id'), and example values, clearly distinguishing it from list-oriented siblings like list_projects.

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 this tool is for retrieving a specific project by ID, contrasting with listing all projects. It explicitly states 'Keyless, open-access metadata' indicating no auth needed, but doesn't mention when to prefer list_projects vs this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds valuable context: the data source (NCI Genomic Data Commons), ranking by case count, and specific fields returned. No contradictions with annotations; the description complements them.

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

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

The description is two sentences, front-loaded with the core purpose. Every word adds value; no redundancy. It efficiently conveys purpose, examples, output fields, and access characteristics.

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 (no output schema, two optional params, annotations covering safety), the description fully addresses what an agent needs: data source, ordering, return fields, and access level. No gaps remain.

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

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

Schema coverage is 100% with both parameters (from, size) described in the schema. The description does not add extra meaning beyond what the schema provides; it only mentions pagination indirectly. 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 lists NCI Genomic Data Commons cancer-genomics projects (with examples TCGA, TARGET, CPTAC), ranked by case count, and specifies the returned fields (project_id, name, program, primary site, disease type). It distinguishes from siblings like get_project (single project) and search_cases/search_files (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 obtaining project metadata but does not explicitly state when to use this tool versus alternatives like search_cases or get_project. No when-not-to-use guidance or prerequisites are provided, though 'Keyless, open-access' hints at no authentication required.

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, idempotentHint, destructiveHint. Description adds context: returns specific fields and defaults to active subscriptions only. 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: first states purpose and output, second provides usage guidance. No wasted words, well-structured 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?

Tool is simple with one optional parameter and no output schema. Description explains return fields and usage, fully covering what an agent needs to know.

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 the only parameter with description, achieving 100% coverage. Description does not add significant additional meaning beyond stating active subscriptions, which is already implied by parameter default. Baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from siblings like 'subscribe' and 'unsubscribe'. It also lists return fields.

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

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

Description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. It gives clear context for when to use this tool.

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

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

The description discloses rate limits (5 per identifier per day), cost (free, doesn't count against quota), and the fact that feedback is read by the team and influences the roadmap. This adds value beyond annotations, which only indicate non-read-only and non-idempotent. No contradictions.

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

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

The description is concise at four sentences, each serving a purpose: what the tool does, when to use it, how to describe feedback, and behavioral notes. It is front-loaded with the core action and wastes no words.

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

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

For a feedback tool with no output schema, the description provides sufficient context: what happens to the feedback (read daily, affects roadmap), rate limits, and quota impact. It does not need to describe return values, as the tool is fire-and-forget. The description fully covers the required information.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds specific guidance on how to use the parameters, e.g., 'Describe the issue in terms of Pipeworx tools/packs' and the meaning of the 'type' enum. This extra semantic context merits a higher score.

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: sending feedback to the Pipeworx team about bugs, missing features, or praise. It uses specific verbs and resources ('Tell the Pipeworx team') and distinguishes itself from siblings by being a dedicated feedback channel, unlike search or query tools.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and what not to do ('don't paste the end-user's prompt'). It provides clear context and exclusions, helping the AI decide when this tool is appropriate versus alternatives.

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

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

Annotations already declare readOnlyHint=true, etc. Description adds valuable context: data source (CF analytics-engine), no PII, aggregation format, and caching (5min-1h). No conflicts with annotations. Could mention if empty results possible, but minor.

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 plus bullet points, front-loaded with core purpose. Every sentence contributes value. No redundant or vague phrases. Highly efficient.

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

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

For a simple tool with one optional enum parameter and no output schema, the description fully covers purpose, usage, parameter semantics, data source, privacy, and caching. No gaps given 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% and already documents the 'window' parameter with enum and description. Description adds pragmatic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds 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?

Description clearly states it returns trending calls (top tools, packs, volume) over configurable windows. It uses specific verbs ('returns') and resource ('what other AI agents are calling on Pipeworx'), distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning with agent needs). Implicitly suggests not for specific queries. Differentiates from siblings by focusing on aggregate trend signal.

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. Description adds rich behavioral context: the types of arbitrage checks (monotonicity, partition_sum), the semantic anchor condition (Jaccard ≥0.30), partition filtering (placeholders >20% return null), and the response structure (opportunities array with specific fields). 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?

Description is comprehensive but slightly long. It is well-structured: start with requirement, then general purpose, then each mode in detail, then additional filters, then response summary. Front-loaded with the mandatory argument condition. Every sentence adds value, but could be tightened by a few 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?

No output schema, but description clearly outlines the response structure (opportunities array with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, etc.). Covers all behavioral aspects: mode selection, semantic matching, partition filtering, failure conditions. For a complex tool with multiple modes, this is very 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?

Input schema coverage is 100% with clear descriptions. The description adds value by explaining the behavior difference between 'event' and 'topic', providing example inputs, and noting that full Polymarket URLs are accepted. This goes beyond the schema's basic property 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 starts with a specific verb+resource ('Find arbitrage opportunities on Polymarket') and immediately distinguishes two modes: single-event ('event') and cross-event ('topic'). It provides concrete examples and explains the underlying checks (monotonicity violations, partition-sum). Clearly differentiated from sibling tools like 'polymarket_edges' or 'polymarket_kalshi_spread' by focusing on arbitrage detection.

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 the required argument condition ('REQUIRES one of event OR topic — call with no args fails') and recommends which mode to use ('event recommended for a specific market', 'topic for cross-event scanning'). Describes when cross-event catches patterns single-event misses, and includes important filters (Jaccard similarity, partition placeholder check). Provides clear when-to-use and when-not-to-use guidance.

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

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

The description discloses extensive behavioral details beyond annotations, including model families, caching ('Cached 1h at the KV level'), diagnostic fields, and caveats like Fed bets being unreliable. Annotations already mark readOnlyHint and idempotentHint, and the description adds valuable context 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 long but well-structured: it starts with the purpose, then details model segments, parameters, and output format. Some redundancy could be trimmed (e.g., repeating knob descriptions), but overall it is logically organized 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, top-level fields) and all parameter behaviors. It covers edge cases like empty segments and caching, making the tool fully understandable for an agent.

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

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

With 100% schema coverage, the baseline is 3. The description adds extra meaning by explaining the tradeable-edge filters (e.g., 'Polymarket has zero trading fees... typically eats 20-50bp per trade') and providing operational context like 'use to suppress thin partitions', which enriches 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 explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb-resource pair and clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on data disagreement and multiple model families.

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 usage context: 'Built for "what should I bet on today"' and advises on knobs like min_liquidity and max_spread_pp. However, it does not explicitly contrast with alternatives (e.g., polymarket_arbitrage) or state when NOT to use this tool, missing some comparative guidance.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds extensive transparency: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains conditions under which spreads are meaningful. 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 detailed and front-loaded with core purpose and modes. While lengthy, every sentence contributes essential information (modes, response fields, safety flags, caveats). Minor reduction could improve conciseness, but structure is logical.

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

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

Given the tool's complexity (two venues, optional parameters, no output schema), the description covers all relevant aspects: input modes, response structure, compatibility warnings, temporal alignment, and counters. It is complete and handles edge cases like non-equivalent bet shapes.

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 brief parameter descriptions. The description adds significant value by explaining the auto-fetch behavior of topic, the override mechanism of explicit tickers, and providing examples. It also details the output structure, which is not in 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use each mode and warns that most pre-mapped topics return compatibility_warning, cautioning that pre-mapped does not guarantee tradeability. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and the behavior of listing all keys when key is omitted, which is useful beyond annotations.

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

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

Three sentences, front-loaded with primary action, no redundant information. 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 single optional parameter and no output schema, description fully explains both retrieval and listing behaviors. 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% and describes the parameter well. Description adds the key semantic of omitting to list all keys, which is 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 explicitly states the tool retrieves a value saved via remember or lists all keys if omitted. It clearly differentiates from siblings remember and forget, which are named.

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 context for when to use (look up stored context) and pairing with remember/forget. Does not explicitly state when not to use or compare to other siblings like search tools, but is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds behavioral context like mark_read affecting future calls and that polling works fine, but does not elaborate on rate limits or other traits. No contradictions.

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

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

The description is concise (~70 words in three sentences) and front-loaded with the main purpose. Each sentence adds useful information without unnecessary verbosity.

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 core functionality, filtering, mark_read behavior, and an alternative access method. It is missing details on the unread_only parameter's effect, but overall sufficient for a read tool with good annotations and schema.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing examples (e.g., 'sec_8k' for type) and clarifying behavior (e.g., mark_read effect), extending beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying what is returned (source, citation_uri, raw payload) and allowing filtering by type and time. It distinguishes itself from sibling tools by focusing on alerts from the feed, not subscriptions or other functionalities.

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 for when to use the tool, including filtering options, mark_read behavior, and the alternative of using the direct API endpoint for scripts/dashboards. It does not explicitly contrast with sibling tools like list_subscriptions but gives sufficient usage guidance.

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

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

Beyond annotations (read-only, idempotent, etc.), the description adds substantial behavioral details: fan-out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail note, handling of 'since' with ISO and relative formats, and return structure (grouped changes, total count, citation URIs).

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

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

The description is front-loaded with example queries and clearly structured. It is a bit dense but every sentence provides necessary information. Could be slightly more concise, but overall well-organized.

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 sources, fallback, relative dates) and absence of an output schema, the description thoroughly covers behavior, parameter options, and return format. It is complete and leaves no major gaps.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the 'since' parameter with examples and a recommendation ('30d' or '1m'), describing 'value' as ticker or CIK, and noting that 'type' only supports 'company'.

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's a change feed for a company in a time window, listing example queries like 'What's new with X' and detailing the sources (SEC EDGAR, GDELT→GNews, USPTO). It explicitly distinguishes from sibling tool entity_profile, making the purpose and scope 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 gives clear context for when to use ('What's new' queries) and points to entity_profile as an alternative for static profiles. However, it does not provide explicit when-not-to-use scenarios or other 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?

Adds significant behavioral context: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions with annotations (idempotentHint true, destructiveHint false). Would benefit from noting if overwriting existing key replaces value.

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?

Well-structured: starts with purpose, then usage guidance, followed by storage details, and pairing instructions. Every sentence adds value, though slightly verbose.

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

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

Given the simple nature of the tool and existing annotations (idempotent, non-destructive), the description provides sufficient context including scope, duration, and pairing. No output schema needed; return behavior is implied.

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

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

Schema descriptions already cover both parameters fully (100% coverage). Description adds contextual examples (subject_property, target_ticker) but no additional syntax or constraints beyond schema.

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

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

Description states it saves data for reuse across conversations or sessions. The verb 'save' and resource 'data' are specific. Distinguishes from siblings recall and forget by mentioning pairing.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward', with examples like resolved ticker, target address, user preference. Also provides pairing instructions with recall and forget.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable transparency: internal cascading through multiple endpoints, auto-disambiguation for companies, and citation URI output. 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?

Well-structured with front-loaded examples, a clear summary, and a detailed breakdown per type. While slightly verbose, every sentence contributes value, and the structure aids readability.

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

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

No output schema exists, but the description explicitly lists return fields for each type, mentions auto-disambiguation, and explains the cascading behavior. It covers enough context for correct usage, though error handling or rate limits are omitted.

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

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

Schema coverage is 100%, but the description adds significant meaning: concrete examples for the `value` parameter (ticker, CIK, name for companies) and explicit enumeration of return fields per type. This far exceeds the baseline of 3.

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

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

Description starts with example queries, states the core purpose (resolving names to canonical IDs), and explicitly distinguishes from siblings with 'Use FIRST whenever you have a name but need an ID.' It covers two entity types with specific output details, making the tool's role 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?

Explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It explains what each type returns and mentions internal cascading to replace multiple manual lookups. While it doesn't list alternative tools for when not to use, the sibling list is broad and the context makes the tool's niche 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 indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. 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 concise (three sentences), front-loaded with the core purpose, and structured logically with no unnecessary words. Every sentence adds value.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description adequately covers what the tool does, how it works, and parameter guidance. It mentions the return format (ranked list with metrics), which is sufficient without an output schema.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it explains the entities parameter treats the first entry as the subject, and the context parameter disambiguates names. Models and _apiKey are also clarified.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs (compare, probe, ranks, surfaces) and specifies the resource (AI visibility). It distinguishes from siblings like ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' and gives an example. It implies when to use this tool vs ai_visibility_check (single entity check). While not stating when-not to use, the guidance is clear and practical.

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 safety traits; description adds concrete behavioral details: bundlephobia delay (5-30s), partial failure degradation, and source-specific error reporting, exceeding annotation coverage.

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

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

Well-structured with front-loaded purpose, usage, and details. Slightly long but every sentence earns its place; could be streamlined slightly but not wasteful.

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

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

For a tool with 2 params and no output schema, description covers all return fields (summary, advisories, links, alternatives), failure modes, and ecosystem scope, leaving 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 covers both parameters fully (100%). Description adds real value: scoped package notation (@types/node), version defaults to latest, and example format, which helps beyond schema but isn't critical.

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's a composite check for npm package analysis, covering deps.dev and bundlephobia, and distinguishes from sibling tools by focusing on safety/popularity/size questions.

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 tells when to use ('is X safe / popular / small', 'what does adding lodash cost me'), when not (NPM only in v1), and handles partial failures gracefully with sources_failed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it is 'keyless, open-access metadata', which provides useful context 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?

Two informative sentences with no waste. Purpose is front-loaded, and key details are efficiently conveyed.

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

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

Sufficiently complete for a simple read-only search tool. Describes purpose, filters, and return fields. Could mention pagination or default size, but size parameter is already in schema. Overall adequate.

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

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

Schema coverage is 100%, so the schema already documents all parameters. Description adds value by explaining what the tool returns and that parameters filter by site/project. This provides extra 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?

Clearly states the tool searches NCI GDC cancer cases by primary site and/or project, and lists specific return fields. Distinguishes itself from sibling tools like 'search_files' or 'search_within'.

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 clear context for use: searching cases by site/project. Mentions 'keyless, open-access metadata' implying no auth needed. Does not explicitly state when not to use or alternatives, but the context is sufficiently clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by listing return fields and stating 'Keyless, open-access metadata,' which discloses authentication requirements and access scope beyond the annotations.

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

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

Three sentences front-load the purpose and return details with no filler. Every sentence adds value, making it highly concise and 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 no output schema, the description adequately covers purpose, parameters, and return fields. It omits pagination details but the size parameter is documented in the schema. For a simple query tool, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description provides example data categories and clarifies that search is by project and/or data category, but this mostly reiterates schema descriptions without adding significant new semantics.

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

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

The description specifies a clear verb+resource ('Search NCI GDC genomic data files') and provides example data categories, distinguishing it from siblings like 'search_cases' or 'search_within' which target different data types.

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

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

The description implies usage for querying NCI GDC file metadata but does not explicitly state when to prefer this tool over alternatives or mention exclusions, leaving guidance implied rather than explicit.

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 rich behavioral context beyond annotations: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K) with truncation flag, and return format details (offsets, scores). 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?

Front-loaded with main purpose, uses short sentences, each adds value. No extraneous information. Efficient and clear.

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

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

Despite no output schema, the description explains return format (top-N passages, offsets, scores) and edge cases (truncation). Completely covers what an agent needs to use this tool effectively.

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. The description adds default values (limit=5), max range (1-20), and example queries, providing additional meaning beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes from siblings by specifying when to use and mentioning the pairing with ask_pipeworx_grounded.

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

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

The description explicitly advises using when the record is too large for the prompt and pairs with ask_pipeworx_grounded. While it implies when not to use, it 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?

Annotations provide idempotentHint=true and openWorldHint=true, but the description adds essential behavioral details: requires OAuth (anonymous/BYO cannot persist), delivery SMS cap (10/day), webhook HMAC signing, and auto-disable after 10 consecutive failures. It also notes that webhook secret is returned once. 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 long but well-structured: starts with purpose and return, then requirements, then supported types with examples, then delivery channels. It is front-loaded and every sentence adds value, though slightly verbose in some parts.

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 3 parameters, full schema coverage, and no output schema, the description adequately covers prerequisites, types, delivery options, limitations (SMS cap, webhook auto-disable), and authentication needs. It is complete for an agent to use 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%, providing baseline 3, but the description adds rich context: examples for type-specific params (e.g., sec_8k items, polymarket_edge topic/min_spread_bps), explanation of delivery channels (feed always on, email, sms with cap, webhook with signing details). This goes well beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream. It specifies that it returns the subscription id and lists supported types (sec_8k, polymarket_edge, fred_series, etc.), distinguishing it from sibling tools like unsubscribe and list_subscriptions.

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

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

The description explicitly mentions when to use: for proactive monitoring. It also hints at alternatives like recent_alerts for pulling the feed, and provides prerequisites (Pipeworx OAuth account). However, it does not explicitly state when not to use this tool or compare with all siblings.

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, which the description does not contradict. The description adds valuable context: it returns 'category-bucketed example questions' with exact tool+argument shapes from a live catalog, and details the behavior of calling with no arguments vs. a specific topic.

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

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

The description is relatively long but front-loaded with the core purpose and usage. Every sentence contributes useful information, though some repetition could be trimmed. The structure uses bullet-like formatting effectively.

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

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

Given only one optional parameter and no output schema, the description fully covers the tool's behavior: it explains the output format (category-bucketed examples with tools+arguments), mentions the catalog size, and clarifies how to use the parameter. Annotations already address safety and idempotency.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, with a clear description listing allowed values and effect of omission. The description's mention of 'pass topic (e.g. "finance", "pharma") to focus' adds examples but does not introduce new meaning beyond the schema.

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

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

The description explicitly states the tool is an onboarding entry point for agents to learn what questions to ask, using phrases like 'what can I ask Pipeworx?' and 'the onboarding entry point'. It distinguishes from siblings by positioning itself as the first tool to call when starting.

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 directly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides explicit alternatives like meta-tools (ask_pipeworx, entity_profile, etc.). It also explains when to omit or use the optional topic parameter.

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 non-read-only, non-destructive, and idempotent behavior. The description adds valuable context about ownership enforcement, deactivation (not deletion), and historical event preservation, which enhances transparency beyond the annotations.

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

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

Two concise sentences, front-loaded with the primary action. Every sentence is essential, providing clear purpose and important behavioral details without verbosity.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, ownership constraints, and the non-destructive effect, sufficient for correct usage.

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

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

The single parameter 'id' is fully described in the schema with coverage 100%. The description merely mentions it, adding no new semantic value beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and scope.

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

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

The description explicitly states when to use the tool (to cancel a subscription by id), enforces ownership ('you can only cancel your own subscriptions'), and explains the behavioral outcome (deactivation vs deletion). This provides clear context for 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: it returns a verdict with structured form, actual value with citation, and percent delta, and replaces multiple sequential calls.

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, front-loading the core purpose with examples. It is somewhat lengthy but each sentence adds value, detailing scope, outputs, and efficiency gains.

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 adequately explains the return value structure. It covers claim scope, supported sources, and the tool's advantage over sequential calls, making it fully informative for an agent.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter. The description adds examples that clarify the expected format, going beyond the schema's basic description.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides clear examples and distinguishes itself from alternative approaches.

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 instructs to use whenever the agent needs to check factual correctness and specifies the domain (company-financial claims). It does not explicitly list when not to use, but the context of sibling tools provides implicit guidance.

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