Gtex

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds detail on return format (per-model score, confidence, signals, raw_response + combined view), cost implications (free default, BYO key for Anthropic), and the default model name.

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 4 sentences, front-loaded with the core action and scoring, then details on models, return value, and use cases. Every sentence adds necessary information without redundancy.

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

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

Given no output schema, the description adequately explains the return format (per-model fields and combined view). It covers the optional API key, default model, and use cases, making it complete for a tool of this complexity.

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

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

All 4 parameters have descriptions in the schema (100% coverage), so baseline is 3. The description adds value by clarifying the default model for 'models', explaining that '_apiKey' is passed straight through, and noting that 'entity' is the thing to ask about.

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 an entity and scores visibility 0-100. It specifies the default model and optional Anthropic probing, distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on general brand awareness.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It gives guidance on when to omit models or provide _apiKey, but does not explicitly exclude alternatives or mention 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral traits: routes to the right tool, fills arguments, returns structured answer with stable pipeworx:// citation URIs. This goes beyond annotations, though annotations cover the safety profile.

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 (~150 words) with some redundancy (multiple examples, repeated use cases). It is front-loaded with key guidance but could be trimmed without losing essential information. 'START HERE for most questions' is good, but overall length is higher than ideal.

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 (routing to 4,770 tools) and the lack of output schema, the description fully covers what the tool does, its inputs, output (structured answer with citations), and when to use alternatives. The context signals and sibling tools are well addressed.

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

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

Schema coverage is 100%, with all parameters described (question and aliases). The description provides examples of valid questions, which adds context but does not add meaning beyond the schema. Baseline 3 applies because schema already serves its purpose.

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

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

The description clearly states the tool routes natural language questions to one of many verified sources, returning structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research. The verb 'routes' and resource '4,770 tools across 1241 verified sources' is 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?

Explicitly recommends using this tool over web search for factual questions, provides when-to-use criteria (e.g., 'what is', 'look up', 'find'), and tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad questions). Also notes it works on every tier.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by detailing refusal reasons, extra LLM cost, and the extraction-only-from-source behavior, providing context beyond annotations without contradiction.

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

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

The description is a single, informative paragraph with no wasted words, but could benefit from structured formatting (e.g., list of refusal reasons) for easier scanning. Efficient overall.

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

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

Given the lack of output schema, the description explains the return format and refusal reasons comprehensively, covering edge cases. It does not detail parameters, but the schema already does 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%, so the description adds minimal value by simply stating 'Your question in natural language' and mentioning aliases already documented in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' for high-stakes reads, specifies the routing and extraction process, and distinguishes itself from the sibling tool 'ask_pipeworx' by noting the extra LLM call cost and appropriate use cases.

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 an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ('Prefer ask_pipeworx for casual lookups'), with concrete examples like financial verdicts and medical 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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds extensive behavioral details beyond annotations: fan-out logic, response shapes, resolver contract, parent event extractor, news fallback handling, safety mechanisms (low-confidence suppression, closed market handling), and resolution-rule risk. 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 very long and detailed, covering many aspects of the tool. While the critical information (purpose, usage) is front-loaded in the first two sentences, the overall length reduces conciseness. Some details (e.g., fan-out examples, response shapes) could be condensed, but they are valuable. Score 3 balances detail with 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?

For a complex tool with 3 parameters and no output schema, the description is comprehensive. It covers input formats, fan-out logic, response structure (market, analysis, evidence, resolver contract, parent event, news fields), safety mechanisms, resolution-rule risk, and guidance on interpreting results (e.g., inspect market_match_confidence). An agent has sufficient information 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 description coverage is 100%: all three parameters (market, depth, include_raw) have descriptions in the schema. The tool description mostly repeats the same information (e.g., accepted formats for market, quick vs thorough for depth, default false for include_raw). It does not add significant meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the verb (research), resource (Polymarket bet), and distinguishes from sibling tools like polymarket_arbitrage which focus on different actions.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains accepted input formats (slug, URL, question text). It does not explicitly state when not to use, but the use cases are clear enough. Sibling tools like polymarket_edges might be alternatives but are not mentioned.

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, and non-destructive behavior. The description adds valuable context beyond annotations: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, and explains result sorting by primary metric. No contradictions.

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

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

The description is dense but well-organized, starting with example queries (front-loaded purpose) and then detailing behavior per type. It could be broken into clearer sections, but 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 (paired data + citation URIs) and sorting behavior. It addresses potential confusion (off-calendar fiscal years) and provides sufficient context 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%, so baseline is 3. The description enhances parameter meaning by explaining what data each type fetches, providing valid value examples, and clarifying constraints (min/max items). It does not merely repeat schema but adds context, justifying 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 states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one call. It includes example queries and differentiates the two entity types, making it easy to understand what the tool does and how it differs from single-entity 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 instructs to prefer this tool over sequential single-pack lookups when comparing entities. Provides clear guidance on when to use type='company' vs type='drug', with examples of valid inputs (tickers, drug names). No alternative tools are mentioned, but the directive to avoid sequential lookups is strong.

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

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

The description discloses behavioral traits beyond annotations: account requirement, paid tier for 'thorough', expected latency (15-60s), return format (evidence, confidence, source, fetched_at, citation, gaps[]), and parallel decomposition. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is well-structured: front-loads the critical account requirement and alternative, then explains the tool's capability, then provides usage guidance. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (1242 sources, 4773 tools, parallel processing, output format, time expectations, account tiers), the description is remarkably complete. It covers prerequisites, behavior, return structure, and limitations.

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

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

Schema description coverage is 100% with both parameters documented. The description adds context about depth meanings ('quick=3, standard=5, thorough=8') but this is already in the schema's description. The description does not add new parameter semantics beyond the schema.

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

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

The description explicitly states the tool performs 'grounded multi-source research across Pipeworx's 1242 structured data sources in ONE call' and distinguishes it from siblings by clarifying it is not open-web search and contrasting with ask_pipeworx for single lookups and breaking news.

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

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

The description provides explicit when-to-use and when-not-to-use guidelines: for single lookups use ask_pipeworx, for breaking news prefer ask_pipeworx, and if not signed in use ask_pipeworx. It also mentions account requirements and paid plan for 'thorough' depth.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds beyond: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 front-loaded with purpose, then provides key usage guidance and output details. Every sentence is informative and 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?

Although there is no output schema, the description fully explains the return value: top-N tools with schemas and examples. It covers all necessary context given the tool's purpose and parameter count.

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 restates that query accepts natural language and aliases, but adds minimal new semantics. The examples in the schema already cover typical usage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb and resource, and the detailed examples distinguish it from sibling tools.

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

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

Explicitly guides the agent: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly defines when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context: fans out across multiple sources, soft-fails for patents, returns specific fields and URIs, and notes limitations (patents API sunset). 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 relatively long but each sentence adds value. It is front-loaded with example queries and structured logically. Minor redundancy could be trimmed, but overall good conciseness 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?

Despite no output schema, the description thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals with keys, patents with soft-fail, news, LEI). It covers all critical aspects for an AI agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by specifying that type only supports 'company' (others coming soon) and that value must be ticker or zero-padded CIK (not names), with examples. This goes beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with specific examples like 'Tell me about X' and lists data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It avoids tautology and distinguishes from chaining single-pack 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 says 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view' and clarifies that names are not supported, advising to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description confirms the delete action and adds context about clearing sensitive data, which aligns with annotations without contradiction. It doesn't add further behavioral details but is consistent.

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

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

Two sentences, front-loaded with the action, no wasted words. Excellent 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?

Given the tool simplicity (one parameter, no output schema), the description fully covers purpose, usage, and pairing with siblings. 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 one parameter 'key' described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so 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 specifies 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from sibling tools like remember and recall.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data' and directly pairs with 'remember and recall', guiding agent to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly a safe lookup. The description adds that it returns 'metadata', but no additional behavioral traits like rate limits or authentication needs are mentioned.

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

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

The description is a single, clear sentence with no unnecessary words. It is efficiently sized for a simple lookup tool, though a brief example or note on return structure could enhance it without sacrificing 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?

Given the existence of an output schema, the description does not need to explain return values. However, 'gene metadata' is somewhat vague, and without seeing the output schema, the description alone leaves ambiguity about what specific fields are returned.

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

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

With 0% schema description coverage, the description must compensate. It states the parameter accepts a Gencode ID or symbol, which aligns with the parameter name, but provides no format details or constraints beyond what the parameter name implies.

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

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

The description clearly states the tool returns gene metadata using a Gencode ID or symbol, which is a specific verb+resource combination. Among siblings like entity_profile, this distinguishes as a focused gene lookup 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 offers no guidance on when to use this tool versus alternatives such as entity_profile or resolve_entity. It does not specify prerequisites or scenarios where the tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds context about the process (fetches page, extracts title/description/key links) and the output format (text blob ready to drop at site-root/llms.txt), but does not disclose potential behaviors like rate limiting or failure handling.

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 three sentences, each adding value: clear purpose, brief process, and practical use cases. No unnecessary words or redundancy.

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

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

The description covers the main purpose, process, and output format. It lacks details on error handling or failure scenarios, but given the simple, read-only nature and the presence of annotations, it is sufficiently complete for an AI agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the meaning of the url parameter with an example and context, but does not add significant new information beyond what is already in the schema.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It explains the process (fetch page, extract metadata, emit standard markdown) and distinguishes from sibling tools like ai_visibility_check by focusing on generation rather than checking.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing a competitor) and implies when to use this tool vs. alternatives like ai_visibility_check. However, it does not explicitly mention when not to use it or provide alternative tool names.

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

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

Adds context beyond annotations: mentions active by default, includes return fields, and implies parameter effect. No contradictions.

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

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

Two concise sentences, front-loaded with purpose and returns, followed by usage guidance. No wasted words.

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

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

Sufficient for a simple listing tool with one parameter. Description covers purpose, returns, and usage context. Annotations fill in safety profile.

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 parameter description is clear. Description does not add extra meaning beyond what 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?

Clearly states it lists the caller's active subscriptions, includes return fields, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Tells when to use: before adding subscriptions or to find an id to cancel. Does not explicitly state when not to use, but context is adequate.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about units (TPM) and scope (across tissues), but does not disclose any behavioral traits beyond what annotations provide, such as rate limits or result structure. With good annotations, this is adequate but not exceptional.

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

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

The description is a single, highly concise sentence that immediately conveys the tool's purpose without any extraneous words. It is front-loaded and every word 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?

The tool is simple and has an output schema, reducing the need for extensive description. However, the phrase 'median expression across tissues' is ambiguous: it could mean the overall median across all tissues or median per tissue. This lack of clarity may confuse the agent, especially with a sibling tool like single_tissue_eqtls. The description does not fully resolve this.

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 fully describes the single parameter 'gene' (Gencode id or symbol), so baseline is 3. The description adds overall context about the result (median TPM across tissues) but does not add new meaning to the parameter itself. No improvement over 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 specifies that the tool returns median expression across tissues for a gene in TPM units. It identifies the resource (gene) and metric (median TPM), clearly distinguishing it from sibling tools like top_expressed_genes or single_tissue_eqtls. However, it lacks an explicit verb like 'gets' or 'returns', slightly reducing clarity.

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 no guidance on when to use this tool versus alternatives such as top_expressed_genes or single_tissue_eqtls. There is no mention of prerequisites, use cases, or exclusions, leaving the agent to infer suitability.

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 show readOnlyHint=false, etc., but description adds critical behavioral details: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also explains the team reads digests daily and signal affects roadmap. 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 concise (~90 words), well-structured with clear sentences, and front-loaded with the core purpose. Every sentence adds value—usage guidance, behavioral notes, and formatting tips—without verbosity.

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

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

Given no output schema, the description could explain what happens after submission (e.g., confirmation). However, it covers rate limits, usage, content rules, and the impact of feedback, which is sufficient for a simple feedback tool. Missing the immediate response is a minor gap.

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

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

Schema coverage is 100% (all 3 parameters described). The description adds value beyond schema by explaining the 'type' enum with real-world examples, specifying 'message' should be 1-2 sentences and 2000 chars max, and advising to describe issues in terms of Pipeworx tools/packs. However, the schema already covers types and structure, so not a 5.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools (which are data/query tools) by being the only feedback mechanism.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also includes a clear exclusion: 'don't paste the end-user's prompt.' No alternative tool exists for feedback, making guidance complete.

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

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

Annotations already convey readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral details: data source ('CF analytics-engine'), no PII, caching duration (5min-1h). 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?

Six sentences total: first sentence states purpose, three bullet points for use cases, then data source and caching info. Every sentence is informative without redundancy. Well-structured and front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description explains returns at a high level (top tools, top packs, total call volume) and caching behavior. However, it lacks explicit detail on the return format (e.g., JSON structure), which would be helpful.

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 description for the 'window' parameter. The description adds extra context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the schema's meaning.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a configurable window, using specific verbs and resource. It distinguishes itself from siblings like 'discover_tools' by focusing on trending/call-volume data.

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

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

Three explicit use cases are provided (discovering hot data, confirming canonical tools, aligning use cases). While it doesn't explicitly state when not to use or compare to alternatives, the context is clear enough for an agent to decide.

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

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

Annotations indicate read-only and idempotent. Description adds significant behavioral details: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and response structure. 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 main purpose, then logically breaks down modes, filters, and check behaviors. Every sentence adds necessary information for correct tool invocation, despite length.

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

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

For a complex tool with no output schema, the description explains the response structure (opportunities[], partition_check, fill_check) and provides sufficient detail for an agent to understand return values and behavior.

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

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

Schema coverage is 100% with descriptions for event and topic. Description adds context: event expects slug, topic expects seed question, and explains behavior when no parameters are provided. This goes beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between scanning modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges 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?

Explicitly explains when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Provides recommendations and rationale (e.g., cross-event catches patterns single-event misses). Also directs to 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?

Disclosures go well beyond annotations: explains caching (1h KV), diagnostics for empty segments model details (lognormal barrier, GDELT, partition overround, concentrated longshot gates), edge calculation (net of slippage, 24h move warning), and filters. No contradiction with annotations (readOnlyHint, idempotentHint, etc.) is present.

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

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

Well-structured and front-loaded with purpose and segments, but very dense. Every sentence provides necessary detail for a complex tool, yet some agents might find it verbose. Good use of formatting and segmentation.

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

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

Despite no output schema, the description fully describes the response structure (by_segment, fed_candidates, diagnostics) and all relevant context (caching, edge calculation, knob effects). For a tool with 9 parameters and three segments, this is exceptionally complete.

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

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

Schema coverage is 100%, baseline 3. Description adds significant context beyond schema, e.g., explaining that min_partition_leg_kelly applies per-leg inside top_legs because partition arbs return 0 at parent level, and clarifying slippage_pp with Polymarket specifics. This elevates understanding despite full schema coverage.

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

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

Description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and distinguishes its purpose as 'what should I bet on today' without paging through markets. It is specific about the verb (scan/return), resource (Polymarket markets), and differentiation from siblings like polymarket_arbitrage by focusing on edge vs arbitrage.

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

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

Explicitly states the use case for discovering daily betting opportunities and includes parameter guidance for filtering (e.g., tradeable-edge knobs). However, it does not explicitly compare to sibling tools like polymarket_arbitrage or provide when-not-to-use scenarios. The context is clear but lacks explicit alternatives.

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

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

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral details: it reads snapshots, tracks expired opportunities, computes trend and decay, and specifies data source (daily closes). This goes beyond what annotations provide.

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

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

The description is longer but well-structured: purpose first, then response format, then limitations. Every sentence adds value, but it could be more concise without losing clarity. It earns its place but is verbose.

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

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

No output schema exists, so the description must explain the return value comprehensively. It does: tracked[], expired[], snapshot_dates[]. Each field is described (e.g., edge_pp_net time-series, trend, decay_pp_per_day, lifespan_days). Limitations are also covered. This fully informs the agent about 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%, with both parameters well-described. The description reinforces defaults (days=14, window='1wk') and adds clamping range for days (2-30) matching schema. It doesn't add new meaning beyond schema but situates params in the tool's context.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge aging and distinguishes itself from sibling tools like polymarket_edges (raw snapshots) and polymarket_arbitrage by focusing on persistence and trend analysis.

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

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

The description provides clear context on when to use the tool, emphasizing that a fresh wide edge differs from an old wide edge. It also includes limitations (60-day TTL, decay from daily closes not intraday) that guide appropriate usage. However, no explicit alternatives are mentioned despite sibling tools existing.

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 readOnly and idempotent. The description adds valuable behavioral context: walks the ladder, returns specific fields, and explains the risk of partial basket fills. 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 clear sections for each mode and a usage guideline. It is slightly long but every sentence adds value, and it fronts the key purpose. Almost perfect, but could be trimmed slightly.

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 return fields for both modes (top_of_book, vwap, etc. for single; theoretical_sum, capture_ratio, etc. for basket). It also describes verdict values and risk elements. Complete for agent 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%, so baseline is 3. However, the description adds rich meaning: explains size_usd for buys vs sells, basket mode settlement notional concept, default side logic in basket mode. This goes well beyond the schema's brief 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 performs an edge check against live order-book depth. It distinguishes two modes (single-market and basket) and lists specific outputs. It explicitly positions itself relative to sibling tools (polymarket_arbitrage, polymarket_edges), differentiating when to use it.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the risks (theoretical overround uncapturable, partial fills converting arb to directional position). This provides clear when-to-use guidance.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explaining exactly what the tool does when legs don't match. No contradiction with annotations.

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

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

The description is thorough but somewhat verbose. However, it is well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds critical context. Slight wordiness prevents a 5.

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 (cross-venue, compatibility checks, temporal alignment), the description is comprehensive. It explains edge cases, counters, and the meaning of response fields despite no output schema. An agent can use this tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds context about the override behavior (explicit parameters override topic mapping) and explains the topic parameter's list of shortcuts. The examples in schema reinforce 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 that the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes its purpose from siblings like polymarket_arbitrage by focusing on a specific cross-platform comparison.

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

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

The description explicitly explains two modes (topic shortcuts or explicit tickers) and warns when not to trust the spread (compatibility_warning conditions, temporal misalignment). It provides actionable guidance for when to use the tool versus when spreads are invalid.

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 scoping detail ('Scoped to your identifier') and listing behavior beyond annotations. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all consistent).

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, purpose front-loaded, no wasted words. Every sentence adds value.

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

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

Given single parameter, no output schema, and rich annotations, the description fully covers scope, behavior, and relationships. Complete for an agent to use correctly.

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

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

Schema coverage is 100% with description. The tool description adds the crucial behavior of omitting key to list all keys, enhancing the schema's meaning.

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

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

Clearly states verb ('retrieve' or 'list') and resource ('value previously saved via remember'). Differentiates from sibling tools 'remember' and 'forget' by describing their relationship.

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

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

Explicitly says when to use ('look up context stored earlier') and pairs with alternatives ('Pair with remember to save, forget to delete'). Provides context for use cases.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context about the mark_read side effect (flagging events read so subsequent calls show only newer ones) and notes that polls work fine, which is useful beyond the annotations.

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

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

The description is concise (4 sentences) and well-structured: it starts with the core purpose, then lists output contents, filtering options, mark_read behavior, and ends with an alternative access method. No redundant or irrelevant 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?

The description covers main use cases, filtering, and mark_read effect, and even mentions an alternative endpoint. However, since there is no output schema, more detail on the return structure (beyond mentioning source, citation_uri, raw event) would improve completeness.

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

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

Schema descriptions cover all 5 parameters (100% coverage). The description adds examples for type (e.g., 'sec_8k') and explains mark_read behavior in more detail, providing value beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying what each alert carries (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions by focusing on reading alert events, not managing subscriptions.

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

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

The description explains filtering by type and since, using mark_read for read tracking, and mentions polling suitability and an alternative REST endpoint. It provides clear context but does not explicitly contrast with sibling tools like subscribe or unsubscribe.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description details multi-source fan-out (SEC, GDELT→GNews fallback, USPTO soft-fail), window interpretation, and return shape (changes[] grouped by source, total_changes, 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?

Single dense paragraph but earns its length: every sentence adds value (purpose, examples, source details, fallback, return structure, sibling pointer). Minor structural improvement possible (e.g., bullet points) but no wasted words.

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

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

Given complex behavior (three sources, fallback, soft-fail, window semantics) and no output schema, the description fully covers return structure, parameter guidance, usage boundaries, and links to sibling. No aspect left unexplained.

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%. Description adds interpretative guidance: 'since' formats explained with examples '7d', '30d', '3m', '1y' plus a recommendation ('Use 30d or 1m for typical monitoring'). 'value' clarifies ticker vs. zero-padded CIK. 'type' notes constraints.

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 opens with concrete example queries ('What's new with X', 'latest on Y'), then states 'change feed for a company in the last N days/weeks/months' with exact sources. Clearly distinguishes from sibling entity_profile by contrasting static vs. windowed data.

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

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

Provides explicit when-to-use examples and closes with a direct alternative: 'Use entity_profile instead when you want the static profile...' No ambiguity about when this tool vs. its sibling is appropriate.

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

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

The description discloses persistence behavior (scope by identifier, persistent for authenticated users, 24-hour retention for anonymous) beyond annotations. It does not contradict annotations.

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

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

The description is three sentences, front-loaded with the purpose, and every sentence adds value without redundancy.

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

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

For a simple two-parameter tool without output schema, the description covers purpose, usage, behavior, and pairing with related tools, making it fully informative.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema examples, staying at 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 'Save data the agent will need to reuse later' using a specific verb and resource. It distinguishes itself from sibling tools like recall and forget by mentioning them explicitly.

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

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

It provides explicit guidance on when to use ('when you discover something worth carrying forward') and pairs with recall/forget, indicating alternatives for retrieval and deletion.

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, destructiveHint=false. Description adds valuable context: tool cascades through multiple lookup endpoints, returns citation URIs for each entity type. 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 examples and purpose. While somewhat long (3 sentences), every sentence adds value. Structured in a way that is 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?

Despite lacking an output schema, description thoroughly explains return values for each entity type (ticker, CIK, RxCUI, etc.) and internal behavior (cascading lookups). Provides complete information for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond enum names and descriptions: provides concrete examples for each type (e.g., 'AAPL' for company ticker, 'ozempic' for drug). Clarifies accepted input formats.

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

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

Description clearly states it resolves names to canonical identifiers, with specific examples like 'ticker for...' and 'CIK for...'. It distinguishes itself from sibling tools as no other tool performs this function.

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.' Provides context for when to use, but doesn't explicitly state when not to use or mention alternatives. Still strong guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: it probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized, including return fields like 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 concise, about 50 words, with front-loaded main action and each sentence adding distinct value: purpose, mechanism, use case. No redundancy.

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

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

Given the four parameters with full schema coverage, no output schema, and rich annotations, the description provides sufficient context. It explains the tool's mechanism, output fields, and a practical use case, covering all necessary information for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter semantics beyond the schema; it mentions entities ordering but that is already in schema description. Other parameters (models, _apiKey, context) are not elaborated in the description.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes from sibling ai_visibility_check by emphasizing multi-entity comparison and competitive audit use case.

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

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

The description provides a concrete use case: competitive AI-marketing audits, with an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or list alternatives. Context is clear but exclusions missing.

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 partial failure behavior and performance caveat (bundlephobia first measurement can take 5-30s), adding context beyond annotations (readOnly=true, idempotent=true). 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 comprehensive yet concise; every sentence adds value. Slightly verbose but well-structured with front-loaded purpose.

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

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

Despite no output schema, the description thoroughly explains return structure (summary block, advisories, links, versions) and error handling, making it complete for a composite 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 description coverage is 100%, baseline 3. Description adds context (package name format, version default, scoped packages) slightly beyond schema, meriting a 4.

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

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

The description clearly states it is a composite check for evaluating adding an npm package, specifying data sources (deps.dev, bundlephobia) and use case ('is X safe / popular / small'). It distinguishes itself from siblings by its specific function.

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 ('whenever an agent asks...') and notes ecosystem limitations ('NPM ecosystem only in v1'), providing alternatives for other ecosystems ('deps.dev:version directly').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: BGE-base-en embeddings with cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Single paragraph that is dense but well-organized: starts with core purpose, then usage guidance, then technical details. Every sentence adds value, no wasted words.

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

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

For a tool with 3 parameters and no output schema, the description covers everything needed: input handling, search mechanics, cap behavior, and return format (offsets, scores). Agent has sufficient information to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema: provides query examples, specifies text max length, limit range and default, and clarifies purpose of each parameter.

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

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

Description clearly states it performs semantic search inside a fetched record, provides examples (SEC 10-K body, article), and explains output (top-N passages with offsets and similarity scores). It distinguishes itself from siblings like ask_pipeworx_grounded.

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

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

Explicitly states when to use: when the record is too big to fit in the prompt, and mentions context saving. References a sibling tool (ask_pipeworx_grounded) for grounding, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds only the word 'significant', implying filtering. It does not disclose pagination, result limits, or other behavioral traits. With annotation coverage, the bar is lower, but the description adds minimal value.

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

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

The description is extremely concise (one sentence). It is front-loaded but lacks critical information. Every sentence should earn its place; this one is too brief to fully inform the agent.

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

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

Given the tool's simplicity (2 parameters, output schema exists), the description is incomplete. It does not explain what eQTLs are, how results are presented, or any constraints. The output schema may provide some context, but the description fails to give a complete picture.

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 0%, so the description must compensate. It mentions 'for a gene' but does not explain the meaning of the 'tissue' or 'gencode_id' parameters beyond what is inferred from the name and schema examples. This is insufficient for an agent to understand parameter semantics.

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

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

The description identifies the tool as providing significant single-tissue eQTLs for a gene. It specifies the resource (eQTLs) and scope (single-tissue, per gene), distinguishing it from siblings like median_expression or tissues. However, it lacks an explicit verb like 'Retrieve' or 'Get', slightly reducing clarity.

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 guidance on when to use this tool versus alternatives. Given many sibling tools related to genes and tissues, the absence of usage context or exclusions is a significant gap.

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

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

The description goes well beyond annotations by detailing return value, account requirements, delivery channel constraints (SMS cap, webhook auto-disable), and type-specific parameter examples. 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 a single dense paragraph that packs much information but lacks structure (e.g., bullet points). It front-loads purpose but becomes verbose.

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

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

With no output schema, the description compensates by stating the return value and covering prerequisites, type options, delivery channels, and constraints. Missing two type values is a gap, but overall adequate.

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

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

Schema coverage is 100%, but the description fails to mention two type enum values (patent_grant, clinical_trial) and does not provide their parameter examples, potentially misleading. For documented types, examples are helpful.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream, distinguishing it from list_subscriptions and unsubscribe. However, it lists only 3 of the 5 supported types from the schema, which could mislead about the full scope.

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

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

The description provides prerequisites (OAuth account) and examples, but does not explicitly compare to alternatives or state when not to use this tool. The context is inferable from sibling tool names.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) already cover safety. Description adds context that the tool returns categorized examples drawn from a live catalog, which is useful beyond annotations.

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

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

The description is concise (4-5 sentences) and front-loaded with natural language triggers. Every sentence provides meaningful information; no wasted words.

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

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

Given no output schema, the description adequately explains the return value (categorized examples with tool calls). It covers purpose, usage, and behavior, making it complete for an onboarding tool.

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

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

Schema coverage is 100% with parameter 'topic' described. Description elaborates by listing example topic values and explaining that omitting gives full spread, adding value over the schema alone.

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

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

The description clearly states the tool's purpose as the onboarding entry point, returning categorized example questions with tool calls. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying this is for initial exploration.

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 this FIRST when you do not yet know what Pipeworx can do' and describes when to pass topic vs omit. No explicit alternatives or when-not, but the guidance is clear for new users.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not add behavioral context beyond stating it's a list operation. 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?

Single sentence, efficient and to the point. Could include more detail but remains concise.

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

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

With output schema and annotations present, the description is adequate but vague. It doesn't clarify what 'tissues' refers to, though siblings hint at biological context.

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

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

No parameters exist. Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific meaning.

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

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

Description clearly states verb 'List' and resource 'tissues'. It conveys the basic purpose, but does not differentiate from sibling tools like 'single_tissue_eqtls' that are more 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?

No guidance on when to use this tool versus alternatives. No context about prerequisites or conditions for 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 convey readOnlyHint, idempotentHint, and destructiveHint false, so the description's burden is reduced. The description adds no further behavioral details (e.g., that results are limited to default dataset), but it does not contradict annotations.

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

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

The description is extremely concise at five words, which is efficient but may be too minimal. A bit more context (e.g., mention of GTEx or default dataset) could be added without significant bloat.

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 an output schema present, the description need not explain return values. However, it lacks context about aggregation method, default dataset, and how it relates to siblings like median_expression, leaving gaps in overall completeness.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add extra meaning beyond what is in the schema; baseline 3 is appropriate.

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

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

The description clearly identifies the resource ('top expressed genes') and the context ('for a tissue'), but it does not include an explicit action verb (e.g., 'list' or 'retrieve') and does not differentiate from siblings like median_expression or single_tissue_eqtls.

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 guidance is provided on when to use this tool versus alternatives. There are no indications of prerequisites, exclusions, or preferred scenarios, leaving the agent to infer usage from the name and schema alone.

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 key behaviors beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical data. No contradiction with annotations.

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

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

Two sentences, front-loaded with the main action, then efficiently adds important nuances. No extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the intended use, behavioral outcomes, and constraints.

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

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

Schema coverage is 100% and already describes the id parameter well. The description adds no extra semantic detail beyond what's in the schema.

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

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

Clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). Distinguishes from related tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement (only own subscriptions) and specifies the behavioral nuance that the row is deactivated, not deleted, so historical events remain accessible via recent_alerts.

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 readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: returns verdict, structured form, actual value with citation, percent delta, and uses SEC EDGAR + XBRL. 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?

Front-loaded with example phrasings, then usage, scope, output details, and efficiency claim. Information-dense but appropriately structured; could be slightly more concise.

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

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

Covers purpose, scope, trigger phrases, limitations (v1 company-financial), output format, data source, and efficiency benefits. No output schema, so description fully explains return values.

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

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

Only one parameter 'claim' with 100% schema coverage. Description adds examples and scope (company-financial claims), providing additional meaning beyond the schema description 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 validates natural-language claims against authoritative sources, specifically company-financial claims from SEC EDGAR. It gives example phrasings and distinguishes itself by replacing multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and lists triggering phrases. It specifies scope (company-financial) but does not explicitly exclude non-financial claims or compare to sibling tools.

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