Edgar

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, and non-destructive. The description adds that it returns per-model scores and a combined view, and that passing `_apiKey` calls Anthropic directly. This provides useful behavioral context 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 two sentences long, front-loads the main action and output, and includes critical details (default model, API key usage) without fluff. It is slightly dense but remains clear and well-structured.

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

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

Given the tool's complexity (4 parameters, no output schema, but clear annotations), the description adequately covers purpose, parameters, and return structure. It mentions the combined view and per-model fields. Minor omission: no mention of timeouts or rate limits, but not critical for a read-only probe tool.

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

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

The input schema has 100% description coverage for all 4 parameters. The description adds value by naming the default model (Workers AI Llama-3.3-70b), clarifying that `_apiKey` is passed straight through to Anthropic, and explaining the `context` parameter's purpose. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for entity knowledge and scoring visibility. It specifies verb (probe, score) and resource (LLMs, entity), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic entity visibility rather than just competitors.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the optional `_apiKey` for Anthropic. It does not explicitly state when not to use, but the context is clear enough for the 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?

The description discloses that Pipeworx selects the best tool and fills arguments, indicating autonomous behavior. No annotations are provided, so the description carries the full burden. It adds value by explaining the orchestration aspect, though it could mention any limitations or scope of data sources.

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

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

The description is concise with three sentences: first states the action, second explains the mechanism, third gives examples. No redundant information, and all sentences serve a clear 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?

Given the simple parameter (one required string) and no output schema, the description is largely complete. It explains how the tool works and provides usage examples. Slightly lower due to lack of mention of return format or potential errors, but still strong for a straightforward tool.

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

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

The only parameter, 'question', is described in the schema as 'Your question or request in natural language', and the description elaborates with examples and the instruction to 'just describe what you need'. Schema coverage is 100%, so baseline is 3; the description adds clear usage context, earning a 4.

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

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

The description clearly states the tool accepts natural language questions and returns answers by automatically selecting the best data source. It explicitly distinguishes itself from sibling tools by noting users don't need to browse or learn schemas, and provides concrete examples.

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

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

The description explicitly tells when to use this tool: when you want to ask a question in plain English without selecting tools or filling arguments. It contrasts with the sibling tools that likely require structured queries or tool selection, giving clear context for usage.

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

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

Annotations already indicate read-only, non-destructive behavior. The description adds value by explaining the fan-out process, classification, and output (evidence packet + comparison). It does not contradict annotations. A minor omission is lack of mention of potential cost or latency, but overall transparent.

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 4 sentences, front-loaded with purpose, and structured logically. Every sentence contributes necessary information. Could be slightly more streamlined, but it's effective and not 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?

The tool has no output schema, so the description must describe return values. It states 'evidence packet plus a simple market-vs-model comparison' but lacks detail on structure or example. Given the tool's complexity, more specificity 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?

The input schema covers 100% of parameters with descriptions. The description adds meaningful context beyond the schema: for 'market', it explains it accepts slug, URL, or question text; for 'depth', it clarifies quick vs thorough. This enhances understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output, and distinguishes from sibling tools like ask_pipeworx by focusing on Polymarket bets and providing a ready-to-use evidence packet.

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

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

Explicit usage contexts are given: 'Use for 'should I bet on X?', 'what does the data say about this Polymarket market?', or 'is there edge in this bet?'. It does not explicitly state when NOT to use, but the clear purpose and examples effectively guide the agent.

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

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

Despite no annotations, the description discloses the types of data returned for each entity type and mentions paired data plus resource URIs. However, it omits details on side effects, authentication, or rate limits.

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

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

The description is concise (two sentences) and front-loaded with key functionality, efficiently communicating purpose, types, and benefits without unnecessary prose.

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 moderate complexity (two types, specific outputs), the description covers input constraints and output nature adequately. Missing output schema is compensated by description, but some details like exact output format are not provided.

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

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

Schema coverage is 100% with clear descriptions. The description adds context about the types' data fields and efficiency, but does not significantly augment the parameter meaning beyond what the schema provides.

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

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

The description clearly states it compares 2-5 entities side by side, differentiates between company and drug types with specific data fields, and highlights efficiency gains by replacing 8–15 sequential calls, distinguishing 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?

The description provides clear context for when to use (comparing entities) and gives type-specific guidance, but does not explicitly mention when not to use or alternative approaches beyond sequential calls.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'the most relevant tools with names and descriptions' and should be called first, which gives useful behavioral context. A minor gap is that it does not mention if the search is case-sensitive or uses semantic matching, but overall it is sufficient.

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

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

The description is three sentences: first sentence states the action, second sentence describes the output, third sentence provides usage guidance. No wasted words, information is front-loaded, and every sentence adds value.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers all essential aspects: what it does, how to use it, when to use it, and what output to expect. It is complete for the 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 the schema documents both parameters. The description adds value by providing an example query format (e.g., 'analyze housing market trends') and noting that the query should be a natural language description. It also mentions the default and max for 'limit', which is beyond the schema's description. Baseline 3, plus extra context gives a 4.

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

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

The description clearly states the tool searches a tool catalog by natural language queries and returns relevant tools with names and descriptions. The verb 'search' and resource 'tool catalog' are specific, and the description distinguishes this tool from sibling tools like 'ask_pipeworx' (which likely answers questions) and 'edgar_*' tools (which are SEC-specific).

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

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

The description explicitly says 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear when-to-use guidance and implies it should be used before other tools, establishing a usage order.

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?

No annotations exist, so description carries burden. Description states it returns 'all reported values across filings for a given US-GAAP concept', indicating a read operation, but does not disclose pagination, data limits, or format. Adequate but lacks depth.

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, concise and to the point. First sentence states purpose, second adds detail about return. No unnecessary words.

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

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

Given no output schema, description is sufficient for a simple retrieval tool with 2 parameters. It covers what is returned (values across filings) but does not mention date range, units, or format, leaving minor gaps.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds no additional meaning beyond the schema examples. The schema already provides clear descriptions for cik and concept.

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

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

Description uses specific verb 'Get' and identifies resource 'financial metric over time for a company', clearly distinguishing it from siblings like edgar_company_facts (which likely returns all facts) and edgar_company_filings (which returns filings).

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

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

Description implies usage for retrieving a specific financial metric over time but does not explicitly state when to use this versus sibling tools like edgar_company_facts (which might return all concepts) or edgar_company_filings. No exclusion criteria or alternatives are 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?

No annotations are provided, so the description must carry full burden. It states the tool returns 'key financial metrics... with their most recent annual values', which adds some behavioral context but does not disclose whether data is limited to annual, what period it covers, or if it includes non-annual data. With no annotations, a score of 3 is adequate but lacking depth.

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-loading the core purpose and then examples. Efficient and no wasted words, but could be slightly more structured (e.g., separating purpose from usage guidance).

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

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

Given no output schema, the description partially compensates by mentioning return of 'key financial metrics like revenue, net income, assets' but does not specify format or structure of response. For a simple tool with one param, it is fairly complete but could detail what is 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?

Schema description coverage is 100% with a single parameter cik. The description adds value by clarifying the format ('e.g., "320193" for Apple') and mentioning the sibling tool edgar_ticker_to_cik for lookup, which goes beyond the schema's basic description.

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

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

The description uses specific verbs ('Get structured XBRL financial data') and resources ('a company by CIK'), clearly distinguishes itself from siblings by mentioning XBRL financial data and most recent annual values, which is unique among the 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?

The description implies usage for retrieving financial data, but does not explicitly state when to use this tool vs alternatives like edgar_company_concept (which may return specific concepts) or edgar_company_filings (which returns filings metadata). There is no guidance on exclusion or 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?

No annotations provided, so description carries full burden. Description clearly states it retrieves recent SEC filings, which is non-destructive. It does not mention rate limits or pagination, but for a straightforward retrieval tool, the behavioral implications are clear.

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 that front-load the purpose and key capabilities. No wasted words.

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

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

Given the tool has 3 simple parameters, no output schema, and no annotations, the description is sufficient. It explains what the tool does, what inputs it takes, and the optional filter. No missing critical information.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by mentioning 'Optionally filter by form type', but the schema already describes each parameter. No additional semantics beyond schema.

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

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

Description clearly states it gets recent SEC filings for a company, accepts ticker or CIK, and optionally filters by form type. The verb 'Get' and resource 'SEC filings' are specific, and it distinguishes from sibling tools like edgar_search_filings (which is likely for searching across companies) and edgar_company_concept/facts (which deal with concepts and facts, not filings).

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

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

Description implies when to use: when you need recent filings for a specific company. However, it does not explicitly state when not to use or how it differs from edgar_search_filings. Context signals show a sibling edgar_search_filings, but the description does not address the distinction.

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?

No annotations are provided, so the description must disclose behavioral traits. It mentions full-text search and optional filtering, but does not clarify aspects like rate limits, result order, or whether searches are case-sensitive. The behavior is adequately described for a search tool, but lacks depth.

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

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

The description is concise with three sentences: first stating the core function, second giving search examples, third mentioning optional filters. No extraneous information, efficiently front-loaded.

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

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

Given the tool has no output schema, the description could clarify what fields are returned (e.g., filing metadata, excerpts). However, for a straightforward search tool with full schema coverage, the description is reasonably 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 description coverage is 100%, so the schema already documents all parameters. The description restates the search capability but does not add significant meaning beyond what the schema provides, such as format expectations or relationship between start_date and end_date.

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 full-text search across SEC EDGAR filings, with specific examples of search types (keyword, company name, topic) and optional filters (form type, date range). This distinguishes it from sibling tools like edgar_company_filings which likely target specific companies.

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

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

The description provides clear usage context (search filings by keyword/company/topic) and mentions optional filters, but does not explicitly guide when to use this tool over siblings (e.g., when to prefer edgar_company_filings or edgar_company_concept).

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?

No annotations are provided, so the description carries the full burden. It describes the tool as a lookup operation, which is non-destructive and read-only. It does not disclose any potential behavioral traits such as rate limits, data freshness, or error handling. With no annotations, a score of 3 is appropriate as it conveys the basic nature without depth.

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, zero waste. Front-loaded with the primary action and resource. Every word serves a purpose. 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 has a single parameter and no output schema, the description adequately explains the purpose and parameter. However, it could be improved by indicating the format of the returned CIK or any prerequisites. Still, it is minimally complete for a simple lookup 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%, so the schema already documents the 'ticker' parameter. The description adds context that the CIK is needed for other tools, but does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool looks up a CIK number from a ticker symbol, and specifies the CIK is needed for other EDGAR tools. Verb ('look up') and resource ('CIK number') are specific, and it distinguishes from siblings which are other EDGAR or memory tools.

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

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

The description mentions the CIK is needed for other EDGAR tools, implying usage context. However, it does not explicitly state when to use this tool vs. alternatives or provide any exclusion criteria. It provides minimal guidance on usage beyond the basic purpose.

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

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

No annotations provided, so description carries full burden. It mentions replacing 10–15 sequential calls and returning 'pipeworx:// citation URIs.' Could add more detail on cost or latency, but overall adequately describes what the tool does and returns.

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 compact (3 sentences), front-loaded with main purpose, then details. Each sentence earns its place with no fluff or repetition.

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 profile tool with 2 params and no output schema, the description provides a comprehensive list of data sources and result format. Could mention if there are limitations like ambiguity or pagination, but overall it's well covered.

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

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

Schema coverage is 100%, but description adds meaning: explains 'type' only 'company', 'value' can be ticker or CIK, and explicitly states names are not supported. This adds value beyond the schema.

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

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

The description clearly states it returns a 'full profile of an entity across every relevant Pipeworx pack in one call,' enumerating specific data sources (SEC filings, XBRL, patents, news, LEI). It distinguishes itself from sibling tools like 'resolve_entity' (for name resolution) and 'compare_entities'.

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

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

Explicitly tells when NOT to use: 'For federal contracts call usa_recipient_profile directly (too slow to bundle)' and instructs to use 'resolve_entity' first if only a name is available. Clear guidance on when this tool is appropriate versus alternatives.

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

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

With no annotations provided, the description bears full burden. It indicates a destructive action ('delete') but does not disclose side effects like whether deletion is permanent or reversible, or any authorization requirements.

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 sentence of six words, front-loaded with the action and resource. It contains no redundant information and is efficient.

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

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

Given the simplicity of the tool (1 required parameter, no output schema, no nested objects), the description is sufficient for basic use. However, it lacks context on the effect of deletion (e.g., cascade effects) or confirmation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it merely restates the parameter 'key' without clarifying format or 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?

The description uses the verb 'Delete' and specifies the resource 'stored memory' with a clear parameter 'key'. It is distinct from sibling tools like 'remember' (store) and 'recall' (retrieve), avoiding ambiguity.

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

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

The description implies use when you need to remove a memory by key, but it does not explicitly state when not to use it or mention alternatives like 'recall' or 'remember' for non-destructive actions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that it fetches the page and extracts data, providing mild behavioral context without contradicting annotations.

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

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

The description is a single, front-loaded paragraph with no wasted sentences. It efficiently conveys purpose, actions, and use cases.

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 with no output schema, the description adequately explains the output format (text blob ready for site-root/llms.txt) and covers needed context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add significant new meaning beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying actions like fetching, extracting title/description/key links, and emitting standard markdown. It distinguishes 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?

The description lists concrete use cases (indexing a client's site, drafting for own project, auditing competitors) but does not explicitly mention when not to use or contrast with alternative tools.

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

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

The description discloses the rate limit (5 per identifier per day) and the cost ('Free'), which are key behavioral traits. It also clarifies that the tool is for feedback only and instructs not to include the end-user prompt. No annotations are provided, so the description carries the full burden and does it well.

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 highly concise: three sentences that efficiently cover purpose, use cases, content guidelines, and limitations. 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 simplicity of the tool (3 parameters, no output schema), the description is complete. It covers the tool's purpose, when to use it, content rules, rate limits, and parameter guidance. No gaps are evident.

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

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

The input schema has 100% description coverage, so the schema already explains each parameter. The description adds context about usage and rate limiting but does not enhance parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states that the tool is for sending feedback to the Pipeworx team, enumerating specific use cases (bug reports, feature requests, missing data, praise). It is distinct from sibling tools like ask_pipeworx, which are for questions.

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

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

The description provides explicit guidance on when to use the tool (for feedback types) and what to include (describe in terms of Pipeworx tools/data, avoid prompt verbatim). It also mentions the rate limit, but does not explicitly state when not to use it versus alternatives, though the context makes it clear.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: data is self-aggregating, derived from CF analytics engine, contains no PII, and is cached for 5 minutes to 1 hour. This goes beyond annotations and helps agents understand freshness and reliability.

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 ~80 words, front-loaded with the core function, and every clause adds meaningful context (use cases, data source, caching, privacy). No redundant or vague phrasing.

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

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

The description mentions return fields (top tools, top packs, total call volume) but does not detail the exact output structure or data types. Given there is no output schema, the description could be more precise about the response format. However, for a simple aggregation tool, the provided information is adequate for basic 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?

The input schema covers 100% of the single parameter (window) with enum and description. The description enhances this by explaining the behavioral difference between short and long windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds semantic value beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a configurable window. It specifies the resource (Pipeworx trending) and action (returns), making the purpose unambiguous. The description also implies a unique use case among siblings by focusing on AI agent aggregation.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical choice, checking alignment). While it does not explicitly state when not to use the tool or mention alternatives, the context signals show many specialized siblings. The description effectively guides selection for trending analysis.

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. The description adds behavioral context by explaining the tool walks child markets, extracts dates/thresholds, and reports violations. 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 comprehensive yet not overly verbose. It front-loads the key concept and efficiently explains the logic without redundancy. Could be slightly tighter but is well-structured.

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

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

With one required parameter, 100% schema coverage, and clear annotations, the description fully covers what the agent needs. It explains the return format despite no output schema, ensuring completeness.

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

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

Schema coverage is 100% and the parameter 'event' has a basic description. The description adds meaning by specifying it can be a slug or URL and explains how it's used, going 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 by checking monotonicity violations. It provides a specific verb and resource ('find arbitrage opportunities within a Polymarket event') and distinguishes itself from siblings like polymarket_edges by detailing the unique logic.

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

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

The description explains when to use the tool (when checking for arbitrage in Polymarket events with multiple date/threshold markets) and gives an example. It could explicitly state alternatives but the context is clear enough.

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

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

Annotations indicate read-only, open-world, non-destructive. The description adds significant behavioral detail: V1 covers crypto-price bets, uses lognormal model from FRED and live coinpaprika, scans top markets, groups by asset, fetches price history once, computes model probability, ranks by |edge|, returns top N with suggested direction. 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 one concise paragraph that front-loads the main purpose. It includes necessary details without being verbose, though it could be slightly more structured with bullet points.

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

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

Despite no output schema, the description explains return values (top N ranked by edge magnitude with suggested trade direction). It covers the complex workflow steps and limitations (V1 crypto-only), providing a complete picture for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining how parameters like limit ('Top N edges'), window ('volume window'), and min_edge_pp ('minimum |edge|') are used, going beyond the schema descriptions.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, specifying resource, action, and context. It differentiates from sibling 'polymarket_arbitrage' by focusing on edge discovery.

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

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

The description explicitly says it's built for the 'what should I bet on today' question, guiding agents to use it for opportunity discovery. It doesn't explicitly exclude cases or compare to siblings like 'bet_research', but the use case is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds that output includes leg-by-leg prices in raw probability and spread in percentage points, and explains the two modes. 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?

Well-structured with clear mode separation and front-loaded purpose. Slightly verbose but each sentence adds value. Could be tightened slightly, but no filler.

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

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

Despite no output schema, description explains return structure comprehensively (leg-by-leg prices, spread). Covers both modes and parameter interactions. Sufficient 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 has 100% coverage (all 3 parameters described). Description adds meaning by explaining how topic mode works (pre-mapped shortcuts) and how explicit tickers override topics, which is beyond schema descriptions.

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

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

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by specifying the cross-venue nature and two modes (topic vs explicit tickers).

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?

Describes two usage modes (topic shortcuts for common events, explicit tickers for custom pairings) and implies use for arbitrage (the delta is a real arb signal). Does not explicitly state when not to use or compare to siblings, but context is clear.

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

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

No annotations are provided, so the description carries full burden. It clearly states the tool is for retrieval (not mutation), and that omitting the key lists all memories. This is sufficient behavioral transparency for a read-only tool. It does not discuss performance or persistence details, but the key behaviors are disclosed.

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, zero waste. The first sentence states the core function, the second provides usage context. Every word earns its place. Front-loaded with the action and resource.

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 (1 optional param, no output schema) and the description is sufficient to use it correctly. It explains both retrieval modes and the context (session memory). Without an output schema, it might benefit from mentioning the return format (e.g., 'returns the value as a string'), but the description is complete enough for a simple tool given the context signals.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the dual behavior: 'Retrieve by key' vs 'list all' when key is omitted. This goes beyond the schema description ('omit to list all keys') by explaining the context of use. It clarifies the optionality and the effect of omission.

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: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' The verb 'retrieve' and the resource 'memory' are specific, and it distinguishes between two modes (by key vs. list all). The tool name 'recall' is well-aligned, and it is distinct from siblings like 'remember' (store) and 'forget' (delete).

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

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

The description provides context for when to use: 'to retrieve context you saved earlier in the session or in previous sessions.' This gives good timing guidance. However, it does not explicitly mention when NOT to use or contrast with alternatives like 'ask_pipeworx' or other tools. No exclusions or alternative tool names are given, so it's slightly less than perfect.

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?

No annotations provided, so description carries full burden. It discloses that the tool fans out to multiple sources in parallel, accepts two date formats, and returns structured changes + count + URIs. This provides useful behavioral context beyond basic purpose.

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

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

Three sentences, front-loaded with purpose, no wasted words. Efficiently conveys all needed information in a well-structured format.

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

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

Given the tool's complexity (multiple sources, parallel execution) and schema richness (3 params with 100% coverage), the description is mostly complete. It covers return structure and usage suggestions. Minor omissions like error handling or rate limits are not critical.

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

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

Schema coverage is 100%, baseline 3. Description adds value: explains type is currently only 'company', details since format options with examples, and specifies that value can be ticker or CIK. This enriches the schema information.

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 returns what's new about an entity since a given time, specifying entity type (company) and data sources (SEC, GDELT, USPTO). It distinguishes itself from sibling tools like entity_profile or compare_entities by focusing on changes over time.

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 usage context: 'Use for brief me on what happened with X or change-monitoring workflows.' Does not explicitly mention when not to use, but the context is clear and implies alternatives are available.

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

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

Discloses persistence behavior (authenticated vs anonymous) beyond what annotations provide. Lacks mention of overwrite behavior on duplicate keys, but annotations are absent so description does well.

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 short sentences, front-loaded with verb and resource, 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?

Tool is simple (2 string params, no output schema), and description covers purpose, usage, and persistence. Could mention key uniqueness or overwrite behavior, but otherwise complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description reinforces purpose of key-value pair and provides example keys, adding context beyond schema.

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

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

Description states verb 'store' and resource 'key-value pair in session memory', clearly distinguishing from sibling tools like 'recall' (retrieve) and 'forget' (delete).

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 to save intermediate findings, user preferences, or context across tool calls', providing clear when-to-use guidance. Also notes persistence difference between authenticated and anonymous 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?

With no annotations, the description carries full burden. It discloses accepted input formats (ticker, CIK, name) and output fields (ticker, CIK, company name, pipeworx URIs). It also notes it replaces multiple calls, implying efficiency. Missing details on error handling or uniqueness, but adequate for a lookup tool.

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

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

The description is two sentences, front-loaded with the primary purpose, then details version, inputs, outputs, and benefit. No unnecessary words.

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

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

Given no output schema, the description explains return values. It covers purpose, inputs, outputs, and benefit. Could mention error scenarios or limitations (e.g., only company type), but is reasonably complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant value by explaining the enum (v1 supports 'company'), providing examples of valid values, and clarifying that 'value' accepts ticker, CIK, or name.

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

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

The description clearly states the tool resolves entities to canonical IDs across Pipeworx data sources. It specifies the verb 'resolve' and resource 'entity', distinguishing it from more specific siblings like edgar_ticker_to_cik by noting it replaces 2–3 lookup 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 provides clear context on when to use the tool (resolve entities to canonical IDs) and gives specific examples for company type. However, it lacks explicit guidance on when not to use it or mention of alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: each entity is probed with ai_visibility_check, results are ranked by score, and the first entity is treated as the subject for narrative. It also mentions the returned fields (score, confidence, signal density), which are not in the output schema.

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

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

The description is two sentences plus a short example sentence, totaling about 60 words. It is front-loaded with the main action and clearly structured. While efficient, it could be slightly more concise by omitting the example quote, but overall it 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?

Given the tool has 4 parameters, no output schema, and reasonable complexity, the description covers the key aspects: what it does, how it works (probing each entity with ai_visibility_check), the ranking behavior, and the return format. It lacks details on optional parameters like context, but the schema covers those. It is sufficiently 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 descriptions for all 4 parameters. The description adds meaning by clarifying that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema. It also restates model defaults and _apiKey usage, but the schema already covers that adequately.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare', the resource 'AI visibility', and the multi-entity scope, distinguishing it from the sibling tool 'ai_visibility_check' which operates on a single entity.

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 usage context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It explicitly mentions the sibling tool 'ai_visibility_check' as the probe mechanism, indicating this is for multiple entities. However, it does not explicitly state when not to use it or mention alternatives like 'compare_entities'.

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

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

The description mentions return values (verdict types, extracted structured form, actual value with citation, percent delta) and the sources used (SEC EDGAR + XBRL). It does not disclose potential failure modes, prerequisites (e.g., valid ticker), or rate limits. Since no annotations are provided, the description carries full burden and provides moderate transparency.

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

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

The description consists of three concise sentences with no redundancy. It front-loads the action ('Fact-check'), quickly establishes the domain and scope, and then lists outputs and benefits. Every sentence adds necessary information.

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

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

Given the complexity of the tool (multi-step reasoning, no output schema), the description covers the main aspects: input, domain, verdict types, and output components. It does not explain edge cases like 'inconclusive' or 'unsupported' verdicts, but the core functionality is well-explained.

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 is fully described (100% coverage) with a clear description of the 'claim' parameter. The tool description adds value by providing example claims and explaining the domain, which helps the agent understand the expected format beyond the schema.

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

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

The description clearly states the tool's purpose: fact-checking natural-language claims against authoritative sources. It specifies the supported domain (company-financial claims for US public companies) and explicitly distinguishes itself from sibling tools by stating it replaces 4–6 sequential agent 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 defines the scope of claims that are supported (company-financial claims) and indirectly suggests when to use it (instead of sequential calls to individual tools). However, it does not explicitly state when not to use it or provide alternative tools for out-of-scope claims.

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