Hgnc

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds crucial behavioral details: default model is free Workers AI Llama-3.3-70b, Anthropic probing requires a key and direct payment, and the API key is passed straight through. 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 a few sentences, front-loads the core action (probe and score), and every sentence adds value—covering use case, model options, cost implications, and return structure. 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 no output schema, the description provides a clear picture of the return value: per-model {score, confidence, signals, raw_response} plus a combined view. Combined with the detailed parameter descriptions, the tool is fully understandable for 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% with good descriptions, but the description enhances each parameter: gives concrete examples for entity, explains model omission defaults to workers-ai, clarifies _apiKey is only needed with anthropic and is passed through, and adds context usage for disambiguation.

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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. It specifies the default model and optional Anthropic probing, distinguishing it from sibling tools like deep_research or compare_entities which serve different purposes.

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

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

The description explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not provide explicit 'when not to use' or directly compare to sibling tools, but the specificity of the task makes its applicability 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, openWorldHint, idempotentHint, destructiveHint=true/false, which the description aligns with. The description adds valuable context: routing to 3,744 tools, returning structured answers with pipeworx:// citation URIs, and being authoritative with citations. 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 efficient at 4 sentences, front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Each sentence adds value: when to use, what it does, how to invoke, examples. While not the most concise, it is well-structured and informative.

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 return format (structured answer with citations). The tool is complex (many sources and tools), but the description covers its purpose, scope, and usage triggers. Sibling tools like deep_research are present, but the description adequately differentiates without needing explicit exclusions.

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% (all 6 parameters are aliases for 'question' fully described). The description reinforces that the tool accepts natural language questions but does not add new parameter semantics beyond what the schema 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 explicitly states the tool answers factual questions using structured data from 3,744 tools across 884 sources, with examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It uses specific verb 'ask' and distinguishes from web search by proactively saying 'PREFER OVER 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 clearly instructs preferring this tool over web search for specific data domains (SEC filings, FDA data, etc.) and lists trigger phrases like 'what is', 'look up', 'find'. It provides examples but does not explicitly state when not to use it (e.g., for subjective opinions or recent events beyond its coverage).

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

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

Beyond annotations (readOnlyHint, etc.), the description adds behavioral traits: hallucination-resistant, uses only tool result, returns specific failure modes (not_in_source, no_tool_match, tool_error, etc.), and costs an extra LLM call. 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 well-structured with purpose first, then behavior, then usage guidelines. Each sentence adds value, covering process, output format, failure modes, and trade-offs without 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 is highly complete for the tool's complexity. It explains the process, documents the return format (including evidence, confidence, source, fetched_at, refusal_reason), enumerates possible refusal reasons, and provides usage guidance. No output schema needed since description covers it.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds little beyond stating 'Your question in natural language', which is already in the schema. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It specifies that it routes through the same system as ask_pipeworx but extracts answers using only the tool result, distinguishing it from the sibling tool.

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

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

Explicitly provides when to use: when answers will be quoted, cited, or acted on, and the agent must not invent facts. Also states when to prefer ask_pipeworx (casual lookups) due to extra LLM call cost, and lists example domains (financial verdicts, legal claims, medical lookups, public statements).

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/read-only behavior, and the description extensively details behavioral traits: fan-out logic, response shapes with edge warnings, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits for low-confidence/closed markets, spread liquidity notes, and cancellation rule parsing. 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 verbose, spanning multiple paragraphs with detailed examples and edge cases. While informative, it lacks conciseness; agents may struggle to parse the essential information quickly. The first sentence is good but the following details are excessive.

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 sub-systems, fan-out, resolver, parent events, news fallbacks, safety features) and the absence of an output schema, the description provides complete coverage of what an agent needs to understand to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by illustrating parameter usage with examples (e.g., 'market_input': 'will fed cut rates...') and explaining the behavior of 'depth' and 'include_raw' beyond the schema definitions. It does not repeat schema descriptions verbatim.

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 researches Polymarket bets by pulling Pipeworx data. It specifies the action ('Research a Polymarket bet'), the resource ('Pipeworx data'), and the types of input (slug, URL, question text). It also lists explicit use cases ('should I bet on X', etc.), distinguishing 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?

The description provides clear usage scenarios ('Use for should I bet on X...') and examples of fan-out for different bet types. However, it does not explicitly state when NOT to use this tool or name alternatives among siblings, though the context signals include 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 already indicate safe, read-only, idempotent behavior. The description adds valuable behavioral details: how off-calendar fiscal years are handled, results sorted by primary metric, and returns paired data with pipeworx:// 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?

The description is comprehensive and front-loaded with example phrasings. It is slightly dense but every sentence adds value. A minor improvement could be to break long sentences, but overall it is well-structured and concise enough for the complexity.

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

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

Given the tool's complexity (two entity types with different data sources, parallel comparison), the description is remarkably complete. It explains what metrics are pulled, sorting order, and return format (paired data + citations). No output schema, but the description covers the essential context, making it fully 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% for both parameters, but the description adds significant meaning beyond the schema. For type, it explains what data is pulled (SEC EDGAR for company, FAERS/FDA/trials for drug). For values, it specifies ticker/CIK format for companies and name format for drugs, plus the 2-5 count constraint. This adds clarity beyond the schema's 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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example queries ('Compare X and Y', 'X vs Y', etc.) and distinguishes from sequential lookups. It also specifies the data sources for each entity type, 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also explains when not to use (comparing entities vs. single lookups) and mentions that it replaces 8-15 sequential lookups, offering strong contextual guidance.

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

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

Annotations already declare safety traits (readOnly, idempotent, non-destructive). Description adds rich behavioral details: returns verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[] for unanswered facets, pre-verified facts, expected time 15-60s, requires Pipeworx account, depth:'thorough' needs paid plan. 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?

Description is fairly dense but every sentence contributes meaning. Could be slightly shorter, but front-loaded with main purpose and key details. Loses a point for length, 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 complexity (parallel processing, multiple sources, verification), the description covers all critical aspects: prerequisites (account), pricing, time, what to expect in output (findings packet, citations, gaps). No output schema, but 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 covers 100% of parameters. Description adds significant value: explains depth values (quick=3, standard=5, thorough=8 paid), clarifies question as natural language fine for broad/multi-part. This enhances usability beyond 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 performs multi-source research in one call, decomposes questions into sub-questions, routes to 3,744 tools across 884 sources in parallel, and returns a structured findings packet. It also distinguishes itself from sibling tool ask_pipeworx for single 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?

Explicitly advises using for broad or multi-part questions with examples like 'compare X and Y's exposure to Z' and 'research the regulatory + financial + market picture for ACME'. Directly contrasts with ask_pipeworx for single lookups.

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 the behavioral context that results include full input schemas with curated examples and are ready to call directly, which goes beyond the 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 concise but packed with information: purpose, use cases, domains, return type, and strategic advice. It is front-loaded with the core function. Only slightly longer than necessary but each 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 simple parameter set (6 params, 100% coverage), annotations that indicate safety, and lack of output schema, the description fully covers what the tool does, when to use it, what is returned, and how to use it. 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 parameters. The description adds value by mentioning keywords like 'query' and 'limit' implicitly, providing examples, and listing aliases (q, task, search, description). This enriches understanding beyond the bare schema.

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

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

The description states 'Find tools by describing the data or task' and lists numerous domains. It distinguishes itself from sibling tools by explicitly positioning it as the first call to discover the option set. The verb 'discover' and resource 'tools' are clear and specific.

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 tells when to use: 'when you need to browse, search, look up, or discover what tools exist' and provides examples. It also advises 'Call this FIRST when you have many tools available and want to see the option set'. While it doesn't explicitly state 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds soft-fail for patents, return count limits (5 filings), and data provenance (SEC, XBRL, USPTO, etc.). No contradictions.

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

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

Description is dense but front-loaded with example queries. Every sentence adds information, though slightly verbose. Could trim some details like patent sunset date.

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 enumerates return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. Provides sufficient context for an agent to understand output structure.

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 value by clarifying that 'value' accepts ticker or zero-padded CIK and explicitly states names not supported, which is 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 uses specific verbs ('profile', 'brief me'), specifies resource ('US public company'), and distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. Examples directly illustrate 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?

Explicitly states when to use (holistic view) and when not to (use resolve_entity if only have name). Provides direct alternative guidance for name resolution.

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 aligns with annotations (destructiveHint=true) by stating 'delete'. It adds context about clearing sensitive data, but does not detail error behavior or side effects. Annotations already provide destructive and idempotent hints.

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

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

Two sentences: first declares purpose, second provides usage guidance. No extraneous information; highly 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 single-parameter delete operation with no output schema, the description fully covers purpose, usage, and pairing. No missing information needed for correct invocation.

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

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

Schema has 100% coverage with a clear description for the only parameter 'key'. The tool description does not add additional meaning beyond what the schema already provides, so baseline score of 3 applies.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes itself from sibling tools by mentioning 'remember' and 'recall' as paired operations.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', guiding proper usage 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?

Annotations already convey read-only, idempotent, non-destructive nature. Description adds behavioral details: fetches the page, extracts title/description/key links, and emits markdown. 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?

Three concise sentences: first defines core function, second explains process, third lists use cases. Front-loaded, no fluff, 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?

Complete given tool simplicity: input URL, optional max_links, output described as text blob. No missing details about return format or side effects. Context signals confirm full schema 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%, so baseline 3. Description adds value by explaining the purpose of max_links (default 25, max 50) and linking parameters to extraction behavior ('title/description/key links').

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 generates a production-ready llms.txt file for a URL, specifying the process (fetch, extract, emit) and output format. Differentiates from siblings by being uniquely focused on this specific task.

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 (client indexing, own project drafting, competitor auditing). Lacks explicit when-not-to-use or alternative tools, but context is sufficient for the niche purpose.

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, destructiveHint. The description adds value beyond annotations by specifying the exact query method (exact by HGNC symbol), the scope (approved human gene), and the return contents (full authoritative record with detailed fields). It also includes a note 'Keyless' implying no authentication key needed.

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 sentence clearly defines purpose and output, second provides usage guidance and a behavioral note. No redundant information, front-loaded with key 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 single parameter and rich annotations, the description fully covers what the tool returns, its usage context, and a behavioral note (keyless). No output schema exists, so the description appropriately lists return 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?

Schema coverage is 100% and the description does not add new parameter-level semantics beyond the schema's own description which includes examples. The tool description reinforces the parameter context but doesn't provide extra format or constraint 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 performs an 'exact lookup' of a human gene by its official HGNC symbol, and enumerates the fields returned (approved name, locus type, etc.). It distinguishes itself from the sibling tool 'search_genes' by emphasizing exact lookup vs. name fragment 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?

Explicitly advises to use 'search_genes' first if only a name fragment is available or if unsure of the exact symbol, providing clear guidance on when to use this tool vs. its alternative.

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. Description adds that it returns specific fields and that it lists active subscriptions unless include_inactive is true, which is not evident from 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 efficient sentences: first states purpose and output, second gives usage guidance. No fluff, 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 simplicity, one optional parameter, no output schema needed. Description covers purpose, output fields, usage, and parameter behavior (via schema). Fully 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 already describes the parameter with 100% coverage. Description does not add additional meaning to parameters 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 clearly states the tool lists subscriptions and specifies the return fields (id, type, etc.), distinguishing it from subscribe/unsubscribe 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 advises using it to review subscriptions before adding more or to find an id to cancel, providing clear when-to-use 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?

Discloses rate limiting ('5 per identifier per day'), cost (free, doesn't count against quota), and the impact on roadmap. Annotations are minimal (no readOnly, idempotent, destructive hints), so the description carries full burden. 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 front-loaded with the core purpose and usage triggers. It is somewhat verbose but every sentence adds value. Could be slightly more concise, but the structure is logical and easy 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?

For a feedback tool with 3 parameters (2 required), nested objects, and no output schema, the description covers all necessary context: purpose, usage guidelines, behavioral notes, and parameter semantics. The agent has sufficient information to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaningful context: explains the enum values for 'type', describes 'context' as optional structured info, and gives guidelines for 'message' (specific, 1-2 sentences, 2000 chars max). This significantly enhances understanding 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's purpose: sending feedback to the Pipeworx team. It specifies four distinct types (bug, feature, data_gap, praise) and explains when each should be used. This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which serve different functions.

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 each feedback type (e.g., 'when a tool returns wrong/stale data' for 'bug'). Tells the agent not to paste end-user prompts and describes how the feedback is processed. Provides clear guidance on alternatives implicitly by differentiating from other tools.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds that the data is self-aggregating, anonymous, and cached with specific TTL. This fully discloses behavior 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?

Description is front-loaded with purpose, followed by return data, use cases, and technical details. Every sentence adds value; no redundancy or fluff.

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

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

Covers all necessary aspects: what it returns, how it's derived, caching behavior, and parameter semantics. No output schema needed as the return is well-described.

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

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

Despite 100% schema coverage, the description adds strategic meaning to the window parameter: shorter windows surface current hotness, longer show steady-state demand. This helps the agent choose appropriately.

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 returns top tools, packs, and total call volume from Pipeworx, with specific temporal windows. It distinguishes itself from siblings like 'discover_tools' by focusing on trending data from other agents.

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 use cases (discovering hot data sources, confirming canonical tool, aligning use case) providing clear context for when to use. No need for when-nots as the use cases are sufficiently exclusive.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details behavioral specifics: requirement of exactly one parameter, walking child markets, checking monotonicity and partition sums, Jaccard similarity filtering, placeholder slug filtering, and the fill check sub-routine that computes realizable edge. 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 front-loaded with the critical requirement (one of event/topic) and is well-structured. However, it is somewhat verbose with technical details like Jaccard similarity, partition filter, and fill check. While informative, it could be more concise without losing essential information.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities[] with fields, partition_check in event mode) and includes sub-routines like fill check. It covers all necessary aspects: parameters, behavior, output, filters, and trade recommendations. Completeness is high for the tool's complexity.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description adds value by clarifying usage examples (e.g., 'fed-decision-may-2026'), recommending modes, and explaining the behavioral differences between event and topic. This extra context justifies 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 clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two distinct modes (event and topic) and provides concrete examples, distinguishing it from siblings like polymarket_edge_tracker and polymarket_fill_risk.

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 requires one of 'event' or 'topic' and warns against calling with no args. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining when each is superior. It also notes when not to trade based on fill check results and references sibling tool 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, which the description fully supports. Beyond annotations, it discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), internal filtering logic, and diagnostic output. No contradictions exist, and it adds valuable context about execution and tradeability.

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 excessively long, delving into technical details of model families and response structure. While well-structured with clear sections, it could be more concise to avoid overwhelming an AI agent. The front-loaded purpose helps, but the length reduces efficiency.

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 absence of an output schema, the description fully explains the response structure, including top-level fields like by_segment, diagnostics, and the meaning of each field (e.g., edge_pp_net, kelly_fraction). It also covers edge cases like Fed bets and filter behavior, ensuring agents understand what to expect.

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 substantial semantic value by explaining the practical impact of each parameter (e.g., slippage_pp advises on typical spreads, min_partition_leg_kelly clarifies why min_kelly doesn't apply). This goes beyond the schema descriptions, making parameter selection more informed.

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 verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explains the tool's purpose for discovering betting opportunities, differentiating it from siblings like polymarket_arbitrage or bet_research. The specific reference to segments and methodology solidifies its unique role.

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

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

The description states it is 'Built for "what should I bet on today"', providing clear context for when to use it. However, it does not explicitly mention when not to use it or compare directly to siblings like polymarket_arbitrage, leaving some ambiguity. Despite this, the purpose is clear enough for an AI agent to infer appropriate usage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: response structure (tracked[], expired[], snapshot_dates[]), limits (history depth, decay computation), and assumptions (daily closes, not intraday). 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 lengthy but well-structured, starting with the core purpose and then detailing response fields. Every sentence adds value, though it could be slightly tighter. It is appropriately sized for the complexity.

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

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

Given no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates), including subfields (first_seen, trend, decay_pp_per_day). It also covers limits and assumptions, making the tool's behavior completely clear.

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

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

Schema covers 100% of parameters with descriptions. The description adds context: days' default 14 and max 30; window's default '1wk' and its meaning as 'snapshot family'. This enriches 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 answers 'how long has this edge existed and is it shrinking?' using edge persistence and decay telemetry. It specifies the resource (polymarket_edges snapshots) and verb (answers). Differentiation from siblings like polymarket_edges (raw edges) is implied by the focus on persistence.

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 when to use: to distinguish between a fresh edge and an old edge. It provides context with limits (60-day TTL) but does not explicitly state when not to use or list alternative tools. However, the distinction from raw edge data 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond annotations by explaining the tool walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and details basket mode risks (thin_legs, forced_directional_risk). 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 with sections for REQUIRES, SINGLE-MARKET, and BASKET, and uses capitalization for emphasis. While somewhat verbose, every sentence adds value and technical details are appropriately front-loaded. Slight reduction in length could improve conciseness, but current structure is 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?

Despite lacking an output schema, the description fully explains return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers edge cases like thin_legs and forced_directional_risk. The tool has two modes and significant risk implications; the description provides complete guidance 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?

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema, such as interpreting size_usd as 'max spend on buys, target proceeds on sells' for single-market, and explaining default side logic for basket ('auto — sell if partition sum > 1, buy if < 1'). This additional context justifies a score of 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 defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and details specific returned fields. The verb 'check' and resource 'fill risk' are precise, and it differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides rationale (partial fills, unhedged directional risk) and distinguishes between modes. The 'above ~$500' threshold implies when it's most critical, providing clear usage 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?

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters), mode behavior, and conditions for meaningful spreads. 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 verbose but well-structured, using bullet points and clear sections. Every sentence adds substantive guidance, though minor redundancy exists (e.g., repeated emphasis on compatibility_warning).

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, two modes, safety fields) and lack of output schema, the description fully covers return format, safety fields, temporal alignment, and warning conditions. An agent has sufficient context to use the tool correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the topic shortcuts list, the override behavior for explicit tickers, and example values, enriching 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 cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies verb ('cross-venue spread'), resource ('Kalshi and Polymarket'), and distinguishes from siblings like polymarket_arbitrage by being venue-specific.

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 details two usage modes (topic shortcuts and explicit tickers), and warns that most pre-mapped topics yield compatibility_warning, implying when not to expect results. It lacks explicit when-not-to-use scenarios but provides clear context for appropriate 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 declare readOnly, idempotent, non-destructive. The description adds important context about scoping ('Scoped to your identifier') and the listing behavior when key omitted, 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 two sentences, front-loaded with the core functionality, and contains no redundant information. Every word 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 retrieval tool with comprehensive annotations and a single parameter, the description covers purpose, usage context, scoping, and sibling relationships. No output schema is needed, and the description provides sufficient completeness for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a clear description of the single parameter ('key'). The description restates the behavior (omit to list all) but does not add new parameter-specific information 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 the action ('Retrieve a value' or 'list all saved keys'), the resource ('saved values from remember'), and directly distinguishes from sibling tools ('remember' and 'forget'). It uses specific verbs and resource references.

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 when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and mentions scoping and pairing with siblings. It lacks explicit 'when not to use' but provides strong contextual 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?

Annotation contradiction: readOnlyHint=true implies no state changes, but description says mark_read:true flags events as read, altering state. This inconsistency undermines transparency.

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

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

Single paragraph, purpose front-loaded, every sentence adds value. No waste.

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?

Covers all 5 parameters, return format (source, citation_uri, payload), use cases (polls, scripts, dashboards). No output schema but description compensates.

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; description adds context (limit default/max, mark_read effect, since filter usage) beyond schema definitions, aiding parameter understanding.

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

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

Clearly states it pulls fired events from subscription feed, returns recent alerts with specific fields (source, citation_uri, payload). Distinct from sibling tools like 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?

Provides guidance on filtering (type, since), mark_read usage, and polling. Mentions alternative endpoint. Does not explicitly contrast with siblings or state 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 declare readOnly, openWorld, idempotent, non-destructive. The description adds: fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic, USPTO sunset soft-fail, return format (changes grouped by source, counts, citation URIs), and relative date parsing. 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: starts with example queries, then explains behavior, parameter details, and alternative tool. Every sentence adds value, no fluff.

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

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

Despite no output schema, the description explains return format (changes grouped by source, total_changes count, citation URIs). It covers limitations (USPTO soft-fail, GDELT preferred). Complete for an info-retrieval 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 description adds context: since accepts ISO dates or relative shorthand with recommendation, value can be ticker or CIK, type only company. This 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?

The description clearly states 'change feed for a company in the last N days/weeks/months' and distinguishes from sibling entity_profile. It provides specific example queries and explains the multi-source fan-out behavior.

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

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

The description gives explicit usage examples, recommends typical since values ('Use "30d" or "1m"'), and explicitly says when to use entity_profile instead. It also explains fallback behavior for GDELT->GNews.

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 include idempotentHint=true and destructiveHint=false. The description adds context on persistence (24h for anonymous, persistent for authenticated) and scope, which are not in annotations. 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 concise (4 sentences) and front-loaded with the primary purpose. Each sentence adds necessary information without redundancy or fluff.

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

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

For a simple write tool with no output schema, the description covers key aspects: purpose, usage, persistence, and pairing with related tools. It could mention overwrite behavior but idempotentHint implicitly addresses that.

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 'key' and 'value'. The description adds usage examples (e.g., 'subject_property', 'target_ticker') and clarifies that value can be any text, enhancing 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's purpose: 'Save data the agent will need to reuse later'. It specifies key-value storage, scoping by identifier, and distinguishes from siblings like 'recall' and 'forget'.

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

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

The description explicitly advises when to use ('when you discover something worth carrying forward') and provides examples. It mentions pairing with recall/forget but does not explicitly state when not to use it, though 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, idempotent, and non-destructive. The description adds that each call cascades internally, replacing multiple manual lookups, and details return fields for each entity type.

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 dense and front-loaded with examples, but slightly verbose. Every sentence adds value, so it remains efficient for the complexity.

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

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

Given no output schema, description explains return values and citation format. Mentions that it replaces several lookups. Lacks error handling or not-found scenarios, but overall sufficient.

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

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

Schema covers both parameters fully; description adds examples, explains accepted input formats (ticker, CIK, name for company; brand/generic for drug), and mentions auto-disambiguation.

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 resolves names to canonical identifiers, provides multiple example queries, and distinguishes it from siblings by positioning it as the first step in a 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 FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. Context from sibling tools like resolve_xref reinforces its role.

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, and destructiveHint. The description adds that the tool performs a reverse-lookup and returns the same full record as get_gene, providing behavioral context beyond the 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 with two sentences. The first sentence states the purpose, and the second provides examples and parameter details. 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 explains that the output is the same full record as get_gene, compensating for the lack of an output schema. It covers the tool's input space completely with examples. Minor omission: no mention of error handling or behavior for invalid IDs, but acceptable for a simple lookup.

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 value by listing acceptable id types (entrez_id, ensembl_gene_id, etc.) and providing formatting examples (e.g., '672' for Entrez), which aids the agent in constructing valid requests.

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 reverse-lookup that maps external database IDs to canonical HGNC genes, with a concrete example ('Entrez 672' -> BRCA1). It explicitly distinguishes itself from siblings like get_gene by noting it returns the same full record, making the tool's 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 explains when to use the tool: when you have an external ID (e.g., Entrez, Ensembl) and want the corresponding HGNC gene. It also mentions it returns the same record as get_gene, implying usage context. However, it does not explicitly state when not to use it or list alternatives, though siblings are available.

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, and destructiveHint = false, so the agent knows it's safe. The description adds behavioral details: 'Probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and mentions return fields (score, confidence, signal density). 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 three sentences long, front-loads the core purpose, and every sentence adds value. No fluff.

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

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

Given no output schema, the description adequately covers return format (ranked list with score, confidence, signal density). It also explains constraints (2-8 entities, first is subject, optional models and apiKey). Annotations cover safety. 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 description coverage is 100%, with detailed parameter descriptions. The description adds minimal extra parameter-level meaning beyond stating that `entities` includes the subject and competitors. This meets the baseline for high schema coverage but does not significantly enhance understanding.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It also distinguishes from the sibling tool `ai_visibility_check` by indicating it aggregates multiple probes into a ranked 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 clear context: 'Useful for competitive AI-marketing audits' and gives an explicit example. It implies not to use for a single entity, but does not explicitly state alternatives or when not to use. The mention of `ai_visibility_check` as the underlying mechanism helps directionally.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description reveals important behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will indicate timeouts. 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 moderately long but well-structured, with the main verb and resource front-loaded. Every sentence provides necessary information, though slight tightening could improve conciseness.

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 return structure (summary block, per-advisory detail, links, alternatives). It completely addresses the tool's complexity and behavior.

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

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

Although schema coverage is 100%, the description adds meaningful context: it explains that package accepts scoped packages like @types/node, and version defaults to the latest. This extra detail 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's specific purpose: a composite check for evaluating npm packages across deps.dev and bundlephobia. It distinguishes itself from siblings by explicitly noting the NPM-only scope and directing other ecosystems to a different 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 defines when to use the tool (e.g., when an agent asks about safety, popularity, size, or cost of adding a package) and provides clear exclusions ('NPM ecosystem only in v1'). This helps the agent select correctly.

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 meaningful behavioral context beyond annotations: describes fuzzy matching, lightweight results, ranking by score, and keyless access. Annotations already indicate read-only, idempotent, and destructive hint false, and 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?

Three sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value: purpose, examples, output format, and next-step recommendation.

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?

Simple tool with two parameters and no output schema. Description fully covers what it does, what it returns, and how to use it, including next step (get_gene). No gaps given tool 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?

Input schema already covers 100% of parameters with descriptions. Description reinforces with examples of query values ('breast cancer', 'p53', 'kinase') and mentions that results include relevance score, 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?

Description clearly states fuzzy search across gene symbols, names, and aliases with examples. It distinguishes from sibling tool get_gene by noting it returns lightweight matches and suggests calling get_gene for full records.

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 recommends using get_gene for full record after search, indicating when to use the tool for initial lightweight search. Lacks explicit when-not-to-use but provides clear 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?

Adds significant value beyond annotations: describes return structure (character offsets, similarity scores), internal details (BGE-base-en embeddings, cosine, 500-char overlapping windows), and truncation behavior (200K char cap with flagging). 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?

Condenses essential info into a single, well-structured paragraph. Purpose immediately front-loaded, no redundant or filler sentences.

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 covers return format (passages with offsets and scores), limits (200K chars), and algorithm details. Also explains integration with sibling tool, making it contextually complete for an AI 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 good descriptions. The description adds examples for query parameter and clarifies the 'text' char limit, providing marginal extra value. Baseline 3 adjusted to 4 due to helpful examples.

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

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

Description clearly states semantic search inside a fetched record, with concrete examples (SEC 10-K, article, tool result). It distinguishes from sibling ask_pipeworx_grounded by explicitly pairing the tools: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' Mentions alternative pairing with ask_pipeworx_grounded, providing clear usage boundaries.

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 beyond annotations: authentication requirement, delivery channel always-on plus optional ones, webhook signing secret one-time return, auto-disable after failures. 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?

Dense single paragraph with all essential information, well-structured. Slightly verbose but 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?

Completely covers prerequisites, types, delivery channels, constraints, and return value for a complex tool with no output schema.

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

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

Provides rich examples and constraints for each parameter, including type-specific params examples and delivery options details. Schema coverage is 100%, and description adds value beyond 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?

Clearly states it creates a subscription to a live-data event stream and returns the new subscription id. Distinguishes from sibling tools like list_subscriptions 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?

Specifies requirement of Pipeworx OAuth account, lists supported types with examples, and describes delivery channels with constraints (SMS cap, phone verification, webhook auto-disable). Implicitly guides when to use but doesn't explicitly state 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, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns category-bucketed example questions drawn from a live catalog, and explains the output format. No contradictions.

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

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

Description is front-loaded with the tool's purpose and common trigger phrases. It lists categories concisely. While slightly lengthy, every sentence adds value, earning 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?

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, what it returns (example questions with tool calls), and the categories. 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% with the topic parameter described. Description adds meaning by explaining 'Call with no arguments for the full spread, or pass topic to focus' and lists possible values, enhancing understanding 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 for an agent to discover what to ask, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings by specifying it's for 'getting started' and 'what data do you have?' while listing meta-tools like ask_pipeworx, discover_tools, etc.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on calling with no arguments for full spread or passing a topic to focus. Lacks explicit when-not-to-use but context is clear.

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

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

The description clearly discloses two key behavioral traits: ownership enforcement ('you can only cancel your own subscriptions') and soft-delete behavior ('The row is deactivated (not deleted)'). These add valuable context beyond the annotations, which only indicate non-destructive and idempotent hints.

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

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

Two concise sentences communicate the core purpose, ownership constraint, and data persistence behavior. Every sentence adds value, and there is no extraneous text.

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

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

The tool is simple with one parameter and no output schema. The description clarifies the non-destructive nature and ownership, which are important. However, it omits what the function returns (e.g., success indicator, updated record) which would be helpful for complete understanding.

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

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

Schema coverage is 100% with one parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds the nuance that the id must belong to the user's own subscription, but this is a behavioral constraint, not parameter semantics. No additional format or default values are specified, so the baseline of 3 is appropriate.

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

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

The description uses the verb 'Cancel' and the resource 'subscription by id', clearly stating the action. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by implying this is the cancellation counterpart, though not explicitly differentiating.

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

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

No explicit guidance on when to use this tool versus alternatives like deactivating via other means or when not to use it. The ownership-enforcement statement hints at a prerequisite, but no when-to-use or when-not-to-use context is provided.

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

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

Annotations already show safe read-only behavior. Description goes further: discloses supported domain (company financials), data sources (SEC EDGAR + XBRL), and return structure (verdict types, structured value, citation, delta). No contradictions.

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

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

Description is moderately long but efficient. Front-loaded with examples and use-case indicators. Each sentence adds value (domain, usage, replacements, return info). 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?

Despite missing output schema, description fully explains return values (verdict, structured form, actual value, citation, delta). Parameter is well-documented. Sufficient for an agent to understand invocation and outcomes.

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?

Only one parameter 'claim' with complete schema description (100% coverage). Tool description adds examples and clarifies natural-language format, enhancing understanding beyond the schema's 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 uses specific verbs ('verify', 'confirm or refute') and identifies the resource ('company-financial claims via SEC EDGAR + XBRL'). It distinguishes from siblings by being a specialized fact-checking tool, whereas siblings cover diverse tasks like entity resolution or betting research.

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

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

Explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct'. Also notes it replaces sequential calls. Lacks explicit when-not-to-use cases, but usage context is clearly defined.

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