Obis

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals that it calls Anthropic if an API key is provided, that the default model is free, and that users pay directly for Anthropic calls. This provides critical operational context not captured by annotations.

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

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

The description is three sentences, each delivering distinct information: action, model options, return format, and use cases. It is front-loaded with the core purpose and efficiently covers key details 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 clearly states the return format (per-model fields plus combined view). It covers the default and optional models, API key requirements, and use cases. It is sufficient for understanding the tool's capabilities, though lacks mention of error or rate limiting.

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

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

Although the input schema covers all parameters (100% description coverage), the description adds valuable context: the default for 'models' is the free Workers AI model, and '_apiKey' is explained as 'BYO key' with direct payment. This enhances understanding 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?

The description clearly states the tool's action (probe LLMs), target (business/brand/product/topic), and output (visibility score 0-100). It distinguishes itself by specifying the default free model and optional Anthropic probing, setting it apart from similar sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to provide an API key for Anthropic probing. However, it does not explicitly exclude scenarios or compare with 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?

The description discloses that the tool routes questions among 3,567 tools across 828 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. This adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), which already indicate safety.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and remains dense with information. Each sentence serves a purpose, and examples are included without unnecessary fluff. It is concise yet comprehensive.

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 that delegates to many sources, the description provides a high-level overview of the routing and citation mechanism. However, it doesn't mention limitations or differentiate from the sibling 'ask_pipeworx_grounded'. Still, it covers the essential context for an AI agent.

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

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

The input schema is fully covered (100%), and the description reinforces the parameter's purpose by explaining the type of questions to ask. While it doesn't add new technical details about the parameter format, it compensates with contextual examples.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data from authoritative structured sources, with citation URIs. It distinguishes itself from web search and lists many example domains, making the scope unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides numerous examples of when to use it (e.g., 'what is', 'look up', 'find'). It also gives concrete query examples, offering strong guidance on appropriate 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?

Discloses extra LLM call cost, return structure (answer, evidence, confidence, etc.), and explicit refusal reasons. Annotations already declare readOnlyHint=true, destructiveHint=false; description adds behavioral context without contradiction.

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

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

Description is thorough but slightly lengthy. Each sentence adds value, and key information is front-loaded. Could trim some redundancy but overall well-structured.

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

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

Given tool complexity (routing through thousands of tools, extraction, refusal handling), description is complete. No output schema, but return format is detailed. Covers errors, cost, and use cases.

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

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

Schema coverage is 100% with all 6 parameters being aliases for 'question'. Description adds no new meaning beyond schema descriptions ('Alias for question'). Baseline 3 due to high 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?

Clearly states it's a hallucination-resistant answer mode for high-stakes reads, with explicit verb 'ask' and resource 'pipeworx' (tool routing). Distinguishes from sibling 'ask_pipeworx' by specifying extraction behavior.

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

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

Explicitly states when to use (high-stakes reads requiring quotes/citations) and when to prefer sibling (casual lookups). Provides concrete examples and alternatives.

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

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

The description extensively covers behavioral traits beyond annotations: resolver contract, match confidence levels, parent event extraction, news fallback, safety blocks for low-confidence and closed markets, and wide-spread tradeability flags. No contradiction with annotations (readOnlyHint etc.).

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 organized with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with purpose. While verbose, every section adds value for such a complex tool. Could be slightly more concise but 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 (multiple classifiers, fan-out patterns, response shapes, error handling), the description is highly complete. It covers edge cases, provides examples, and explains response fields and safety checks. No output schema exists, so the description carries the full burden and succeeds.

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

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

Schema description coverage is 100%, so the description adds minimal semantic value beyond what the schema already provides. It does explain the behavior of 'include_raw' but the schema itself already details it. Baseline of 3 is appropriate.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, with specific verb and resource. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research and evidence gathering.

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 provides usage scenarios ('should I bet on X', 'what does the data say about Y') and gives fan-out examples per classifier. It lacks explicit when-not-to-use or alternative tool recommendations, but overall guidance 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?

Adds rich behavioral context beyond annotations: explains EDGAR/XBRL source, fiscal year handling, FAERS data, sorting by metric, and citation URIs. All consistent with readOnly/openWorld/idempotent hints.

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

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

Slightly verbose but front-loaded with example queries. Every sentence adds value. Could be tightened but still effective.

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

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

Complete for a comparison tool with no output schema: explains data sources, sorting, number of entities, and return format includes citation URIs. 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?

Despite 100% schema coverage, description adds meaningful detail: for company it lists exact financial fields and ticker examples, for drug it lists counts and drug name examples. This greatly aids agent 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?

Description explicitly states the tool compares 2–5 companies or drugs side-by-side, and specifies the data sources (SEC EDGAR for companies, FAERS for drugs). It is a specific verb-resource combination with clear scope.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives example phrases (e.g., 'Compare X and Y'). Could mention alternatives like entity_profile but strong guidance exists.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about output format (top-N tools with full schemas and examples) and that results are ready to call directly, with no contradiction to 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 the core purpose. Every sentence adds value, covering usage, domains, output, and strategic advice without extraneous detail.

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 discovery tool with 6 parameters (mostly aliases) and no output schema, the description adequately explains what the tool returns (relevant tools with schemas and examples) and lists many covered domains. Lacks explicit mention of pagination, but that is minor given the tool's simplicity.

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

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

Schema coverage is 100% with descriptions for all parameters. The description does not add significant parameter-specific semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists specific domains, and explicitly positions it as a discovery tool to call first, distinguishing it from sibling tools that answer specific queries.

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

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

The description explicitly states when to use ('when you need to browse, search, look up, or discover') and advises calling it first when many tools are available, though it does not explicitly exclude cases when the agent already knows which tool 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?

The description discloses key behavioral traits: fans out across multiple sources, returns specific data fields, notes patent API sunset and soft-fail behavior, and news fallback. This adds significant context beyond the annotations, which already indicate read-only, idempotent, open-world, and non-destructive.

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 given the complexity of the tool. It is front-loaded with example queries and every sentence adds value. Slightly more structure could help, but it 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 lack of an output schema, the description thoroughly explains the return values (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and includes fallback behaviors and limitations. It covers all essential 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% with descriptions. The description adds value by providing concrete examples (ticker 'AAPL', zero-padded CIK '0000320193') and reiterating that names are not supported. This clarifies the expected format beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company'. It provides multiple example queries and explicitly notes its preference over chaining individual lookups, distinguishing it from single-source 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 gives explicit when-to-use guidance via example queries and the directive 'ALWAYS PREFER over chaining...'. It also states when not to use: names not supported, advising to use resolve_entity first. Usage context is fully covered.

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, destructiveHint) already indicate safe read operation. The description adds that it returns total match count plus a sample of records and identifies the data source (OBIS). No contradictions.

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

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

Two sentences, front-loaded with the core purpose and key details. No redundant or extraneous information. Efficient 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?

For a simple query tool with 4 parameters and no output schema, the description adequately covers purpose, return value (sample + count), and optional parameters. Could mention that limit controls sample size, 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?

Input schema has 100% description coverage; descriptions for parameters are clear. The tool description adds context about date filtering but does not provide additional meaning beyond the schema descriptions. 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 finds georeferenced marine occurrence records for a scientific name from OBIS, listing the fields returned (latitude, longitude, date, depth, country, locality, basis of record) and optional date filtering. It is specific and distinguishable 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 mentions optional date range filtering but does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives among the sibling tools. Usage context is implied rather than stated.

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

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

Description aligns with destructiveHint: true, adds context on clearing sensitive data and stale context. 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 efficient sentences. First states purpose, second provides usage guidance. 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?

Complete for a simple delete tool. Annotations already cover safety; description adds usage 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?

Single parameter 'key' with schema description. Description does not add beyond schema; baseline score 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?

Clear verb 'delete', specific resource 'memory', method 'by key'. Distinguishes from siblings '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?

Explicitly states when to use: stale context, task done, clear sensitive data. Also pairs with related tools.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds process details (fetches, extracts title/description/key links, emits standard format) without contradicting annotations. No side effects disclosed, but safety is clear from annotations.

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

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

Three focused sentences: first states purpose and audience, second explains core action, third describes output and use cases. No redundant words; front-loaded with key information.

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

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

For a tool with 2 params, no output schema, and rich annotations, the description fully covers purpose, process, output format, and use cases. All necessary information is present.

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

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

Schema coverage is 100% with good descriptions for both params (url, max_links). The description does not add semantic depth beyond what schema provides; it only restates the process. 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 a production-ready llms.txt file for any URL, with specific verb 'generate' and resource 'llms.txt'. It distinguishes itself from siblings (e.g., ai_visibility_check) by focusing on file creation for AI crawlers.

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

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

Explicit usage scenarios are provided: getting a client’s site indexed, drafting for own project, auditing competitor sites. However, it lacks when-not-to-use or alternative tools, though context implies specific use case.

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, etc. The description adds context about the return fields but does not disclose additional behavioral traits such as response time, rate limits, or how openWorldHint affects results. The value added beyond annotations is moderate.

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 that is front-loaded with the action and resource, followed by a list of returned statistics. Every word is necessary; no redundancy or 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?

Given the tool's simplicity (one parameter, no output schema needed), the description fully covers the input and expected output. It lists all return fields, making it self-contained. No additional details are required.

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

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

Schema coverage is 100% and the schema provides a clear description with an example for the single parameter. The description mentions 'marine taxon' but does not add new semantic meaning beyond 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 specifies the verb 'Get', the resource 'aggregate OBIS statistics', and lists the exact fields returned (total occurrence records, distinct species/taxa, contributing datasets, observed year range). It distinguishes from siblings like 'find_occurrences' and 'get_taxon' by emphasizing aggregated statistics.

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 when aggregate statistics for a marine taxon are needed, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative suggestions are provided.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. Description adds value by detailing exact return fields (taxon ID, rank, accepted name, hierarchy, occurrence count) and explaining OBIS's marine scope.

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, each substantive. Front-loaded with the tool's purpose and output, followed by context. No redundant or filler text.

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

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

For a simple, single-parameter tool with comprehensive annotations and schema, the description adequately explains purpose, output, and context. Missing details like error handling or rate limits are acceptable given simplicity.

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

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

Single parameter 'name' has full schema coverage with an explicit example. The tool description itself adds no additional parameter information beyond what the input 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?

Description clearly states it resolves a marine name against OBIS and lists returned fields. Specific verb 'resolve' and resource 'OBIS taxon record' provide clarity, though sibling differentiation via 'marine focus' is implicit.

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

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

Provides context that OBIS is for marine biodiversity and complements GBIF, but does not explicitly state when to use this tool versus alternatives like find_occurrences or resolve_entity.

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, so the description's additional detail about returned fields and default scope adds modest value. No contradictions.

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

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

Two sentences maximize information density with zero 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 simple list tool with one optional parameter and no output schema, the description fully covers purpose, returned fields, and usage 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 has 100% description coverage for the single optional parameter. The description does not add extra meaning beyond the schema's description of 'include_inactive'.

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

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

The description clearly states the verb 'List' and the resource 'caller's subscriptions'. It also enumerates the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly guides when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context, though it doesn't explicitly state when not 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 are all false and neutral; the description adds valuable behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily impacting the 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 front-loaded with the primary purpose and is largely efficient, but at ~100 words it is slightly verbose for a simple feedback tool. All sentences earn their place, but a minor trim could improve conciseness.

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

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

Given the tool's low complexity (3 parameters, no output schema), the description fully covers purpose, usage, behavioral traits, parameter details, and contextual impact (roadmap). No gaps remain.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains each enum value in plain language (e.g., 'bug = something broke or returned wrong data'), elaborates on the 'context' object's optional nature, and provides guidelines for the message (be specific, 1-2 sentences, 2000 chars max). This adds value beyond the raw 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 defines the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and distinguishes the tool from siblings; none of the 28 sibling tools serve a feedback purpose.

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

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

The description provides precise guidance on when to use the tool: '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).' It also gives a clear negative instruction ('don't paste the end-user's prompt') and specifies rate limits and cost.

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 adds value beyond annotations by explaining the data is self-aggregating, derived from analytics engine, contains no PII, and is cached with time ranges. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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 (3-4 sentences), well-structured with a clear lead sentence, bullet-style use cases, and technical detail at the end. No superfluous words.

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

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

The description covers data source, caching, and use cases but lacks explicit return format (e.g., JSON structure). Since there is no output schema, a brief mention of the output shape would improve completeness. Still, the tool is simple.

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 provides enum description for 'window', but description adds meaning by explaining what each window implies (shorter for hot, longer for steady-state). With 100% schema coverage, this extra context elevates the score.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', using the specific verb 'returns' and identifying the resource. It distinguishes itself from siblings like 'discover_tools' by emphasizing self-aggregating signal derived from analytics, not external 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?

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tool, seeing alignment) and provides guidance on window selection. However, it does not explicitly state when not to use this tool or mention 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?

The description provides extensive behavioral details beyond annotations: it explains the requirement for a parameter, the arb detection logic (monotonicity violations, partition checks), semantic anchor (Jaccard similarity), partition filter, response structure, and edge cases like null arb signals. Annotations already indicate readOnly, openWorld, and idempotent, and the description adds rich context without contradiction.

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

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

The description is long but well-structured with clear sections, bold headings, and case for emphasis. While it contains technical jargon and is dense, every sentence adds value and the structure aids readability. A slight reduction in length could improve conciseness, but overall it is effective.

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

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

Given the tool's complexity (two mutually exclusive parameters, no output schema), the description provides complete context: it covers parameter requirements, usage modes, the algorithm, response fields, and special conditions (e.g., placeholder filters, similarity thresholds). It effectively compensates for the lack of an output schema by describing the response structure.

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

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

The input schema already covers both parameters with descriptions, but the tool description adds significant meaning: it explains that 'event' accepts slugs or URLs (with examples), that 'topic' uses a seed question, and details the behavioral differences between the two modes. This goes well beyond the schema alone.

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

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

The description clearly states the verb 'Find' and the resource 'arbitrage opportunities on Polymarket', and specifies two modes (event and topic). It distinguishes the tool's functionality from siblings like polymarket_edges by detailing the specific arbitrage detection methods (monotonicity violations and partition-sum checks).

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

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

The description explicitly requires one of 'event' or 'topic' parameters and warns that calling with no args fails. It recommends 'event' for a specific market and 'topic' for cross-event scanning, and explains the advantages of cross-event mode. However, it does not explicitly state when not to use the tool or provide alternatives, but the guidance 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 indicate readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds extensive detail: caching (1h KV), three opportunity segments with model families, edge calculation with slippage, Kelly fractions, liquidity/spread filters, and diagnostics. 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 very long and dense with technical details. It front-loads purpose but becomes verbose. It could be more concise while retaining essential information.

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

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

Given the tool's complexity (9 params, no output schema), the description covers almost all behavior: segments, edge calculation, filters, diagnostics, and caching. It lacks a structured output schema description but compensates with inline details.

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

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

Schema covers all 9 parameters with descriptions. The description adds extra context, such as explaining min_partition_leg_kelly vs min_kelly interaction, Fed note, and defaults. This adds meaning beyond the schema, but baseline is 3 due to high coverage.

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

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

The description starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' providing a specific verb and resource. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx disagreements and opportunity discovery.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies when to use and provides context like Fed bets being unreliable. However, it lacks explicit when-not-to-use or alternative tool recommendations.

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

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

Beyond annotations (readOnlyHint, etc.), the description fully discloses behavioral traits: leg-by-leg prices, spread calculation, compatibility warnings for non-equivalent bet shapes, temporal alignment flags, and skipped comparison counters. It explains what makes spreads meaningless (e.g., temporal misalignment, non-equivalent bet shapes).

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

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

The description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes meaning, though minor verbosity reduces conciseness 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 the absence of an output schema, the description covers the response structure (leg-by-leg prices, spread, safety fields, temporal alignment) adequately. It explains rare edge cases (non-equivalent bet shapes, unrelated events) but could specify exact output format more precisely.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the two modes and how explicit parameters override topic-mapped ones, going beyond the schema's simple enumeration of values.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It specifies two modes (topic shortcuts vs explicit pairings) and details the response structure, distinguishing it from sibling tools like polymarket_arbitrage or bet_research that focus on single-venue 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 explains when to use topic mode vs explicit mode, and warns that pre-mapped topics often return compatibility warnings, advising that pre-mapped ≠ tradeable. It details conditions for safety fields but does not explicitly contrast with sibling tools for alternative 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds valuable context about scoping ('Scoped to your identifier') and the listing behavior, but does not detail return format or error cases, which is acceptable given 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, front-loaded with the action, and every sentence adds value. It efficiently covers retrieval, listing, use case, scoping, and related tools without waste.

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

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

Without an output schema, the description explains the return values ('a value' or 'list all keys'). It covers scoping and pairing with remember/forget. Minor details like error handling are omitted, but overall adequate for a simple key-value retrieval tool.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description repeats this information without adding additional meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys.' It explicitly distinguishes from siblings by naming 'remember' and 'forget' as partners, making the purpose unambiguous.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier') and implies when not to (by pairing with remember and forget). It does not explicitly state alternatives to avoid, but provides sufficient guidance for an agent.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable behavioral details: the effect of mark_read (flags events read so next call shows newer ones), that results are 'most recent,' and that each event carries specific fields. 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 four sentences, each earning its place. It front-loads the purpose and efficiently covers capabilities, fields, filtering, and side effects. 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 return fields (source, citation_uri, payload). It covers filtering options and mark_read behavior. Missing details like sorting order (by fired_at) and pagination limits, but the tool is simple and the description is sufficient for typical use.

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

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

Schema coverage is 100% with parameter descriptions. The description adds extra context: gives example for type ('sec_8k'), clarifies that mark_read affects subsequent calls, and mentions ISO format for since. This goes beyond the schema, adding semantic value.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts), the action (pull/retrieve), and distinguishes from siblings like subscribe/unsubscribe by focusing on reading alerts. The mention of key fields (source, citation_uri, payload) further clarifies what the tool delivers.

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 good context: it notes that polling works fine and mentions an alternative API endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or directly compare to sibling tools like list_subscriptions. The scope of usage is clear but could be more precise.

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, openWorld, idempotent, non-destructive. Description adds fan-out behavior, fallback logic (GDELT preferred, GNews on rate limit), and soft-fail for USPTO, enhancing 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?

Compact single paragraph, front-loaded with use cases, then details, then alternative. Every sentence is informative; 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 multiple sources, fallback behaviors, and no output schema, the description covers return structure (changes[], total_changes, URIs) and sibling tool guidance. Complete for effective use.

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

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

Schema covers all parameters (100%). Description adds examples for `since` (ISO and relative), explains `value` (ticker or CIK), and clarifies `type` (only company). Adds meaningful usage context.

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

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

The description explicitly states it provides a change feed for a company over a time window, with clear examples like 'What's new with X' and distinguishes from sibling tool 'entity_profile'.

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 gives explicit when to use (e.g., 'latest on Y') and when not to ('Use entity_profile instead when you want static profile'), providing clear 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?

Description adds significant behavioral context beyond annotations: explains scoping by identifier, persistence (24 hours for anonymous, permanent for authenticated), and the idempotent nature of storing same key again. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four sentences packed with value, no fluff. Front-loaded with the core purpose, then usage guidance, then behavioral details, then companion tools. Each sentence earns its place.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, behavior (scoping, persistence), and parameters adequately. Annotations provide additional safety traits. Complete for the tool's complexity.

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

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

While schema coverage is 100% with descriptions for both key and value, the description adds practical examples of key patterns (e.g., 'subject_property') and specifies that value is 'any text'. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (e.g., resolved ticker, target address). It differentiates from siblings by mentioning companion tools 'recall' and 'forget'.

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

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

Provides clear usage guidance: 'Use when you discover something worth carrying forward...' and explains persistence differences for authenticated vs. anonymous users. Although it doesn't explicitly state when not to use, the context 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?

Annotations already declare safe, idempotent, read-only behavior. The description adds value by disclosing internal cascading through multiple endpoints and detailing return fields (e.g., ticker, CIK, RxCUI, citation URIs). 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?

Well-organized with examples and structured lists. Slightly lengthy but each section adds value; front-loaded with key purpose. Could be marginally tighter but 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?

Despite no output schema, the description fully explains returns for each type, including citation URIs. Covers all necessary context for agent to use the tool correctly.

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

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

Schema coverage is 100% with basic descriptions. The description adds concrete examples and formats (e.g., 'ticker (AAPL), CIK (0000320193), or name') providing extra clarity 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 resolves names to canonical identifiers, provides example queries, lists supported types ('company', 'drug'), and distinguishes from siblings by advising 'Use FIRST whenever you have a name but need an ID.'

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 ('Use FIRST whenever you have a name but need an ID') and notes it replaces 2-3 manual lookups. Does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotent, non-destructive. Description adds that it probes each entity with a sub-tool and returns ranked scores, confidence, signal density. No contradictions; extra detail on return structure is valuable.

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

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

Two efficient sentences plus a brief return description. Every sentence adds value: purpose, process, example, output. 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?

Covers all key aspects: input (entities, models, context, API key), behavior (probes, ranks), output (ranked list with fields). No output schema exists, so description fills that gap well.

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%, providing baseline 3. Description adds value by noting that the first entity in 'entities' is the 'subject' for narrative and that 'context' disambiguates common names, which is beyond schema.

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

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

Description starts with a clear verb-resource pair ('Compare AI visibility across multiple entities side-by-side') and explains the process (probe with ai_visibility_check, rank results). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic compare) by focusing on AI presence.

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

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

Explicitly states use case ('competitive AI-marketing audits') with an example question. Does not explicitly list when not to use, but the context of sibling tools (e.g., ai_visibility_check for single entity) implies appropriate scenarios.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral details: fans out across two services, returns specific fields, handles partial failures, and notes bundlephobia's first measurement delay.

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 block but well-structured: purpose, usage, return format, limitations. Front-loaded with key info. Slightly long but every sentence earns its place; could be broken into paragraphs for readability.

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

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

No output schema exists, so the description fully covers return values (summary block fields, per-advisory detail, links, alternative versions) and error handling (sources_failed). Comprehensive 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 coverage is 100%, so baseline is 3. The description adds examples (scoped packages, version '18.3.1'), clarifies that version defaults to latest, and explains that scoped packages are accepted.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia data. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on package safety/size/cost.

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 ('is X safe / popular / small') and when not to ('NPM ecosystem only in v1; other ecosystems fall under deps.dev:version directly'). Also covers partial failures and timing caveats.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds critical behavioral context: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. No contradictions with annotations.

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

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

Three sentences efficiently convey purpose, use case, technical details, and constraints. Front-loaded with main action and resource. Every sentence earns its place; no wasted words.

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

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

Despite no output schema, description fully explains return values (top-N passages with character offsets and similarity scores). Covers input constraints (200K char cap, truncation flagging) and technical approach (BGE-base-en, cosine, 500-char windows). Satisfies all information needs for correct invocation.

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

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

Input schema covers all 3 parameters with 100% description coverage. Description adds value by explaining purpose of each parameter (e.g., 'the document text to search inside'), providing example queries, and clarifying default behavior for limit. Goes beyond schema with natural-language examples.

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

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

Description precisely states 'Semantic search INSIDE a fetched record' with specific verb (search), resource (record), and method (semantic). Differentiates from siblings like ask_pipeworx_grounded by explaining pairing use case. Clearly defines inputs and outputs including passage offsets and scores.

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 cram into the prompt'. Mentions pairing with ask_pipeworx_grounded as a workflow alternative. Lacks explicit when-not-to-use scenarios but context is clear enough for proper selection.

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 contradicts annotations: it describes a write operation (creating a subscription) while annotations set readOnlyHint=true. This is a serious inconsistency. Additionally, it lacks details on security implications beyond OAuth requirement.

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, well-structured, and front-loaded with the main purpose. 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 (3 params, nested objects, no output schema), the description covers return value, prerequisites, delivery behavior, and limits. It is fully adequate 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%, baseline 3. The description adds significant meaning: explains type enum, param structure with examples and defaults, delivery channel details (validation, limits). This goes beyond the schema's minimal descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription' with a specific event stream type and examples. It implicitly differentiates from sibling tools like list_subscriptions and unsubscribe, but does not explicitly contrast with them.

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 specifies the use case, required account type, delivery options, and limits (10 SMS/day). It does not explicitly state when not to use this tool, but provides enough context for appropriate usage.

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

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

The description claims a mutation operation ('Cancel'), but annotations declare readOnlyHint=true, creating a direct contradiction. The description adds deactivation context but fails to resolve the inconsistency, severely undermining trust.

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, each informative with no redundancy. Action is front-loaded and all content earns its place.

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

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

Despite low complexity and full schema coverage, the contradictory annotation undermines completeness. No return value explanation or mention of post-cancellation behavior (e.g., status changes). The description attempts to clarify but misses critical details for a mutation 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% for the single parameter (id), which already states it's a uuid from subscribe. The description adds ownership enforcement context but does not enhance parameter syntax or 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 'Cancel a subscription by id' with a specific verb and resource, and distinguishes it from sibling 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 mentions ownership enforcement ('can only cancel your own subscriptions') and explains that the row is deactivated not deleted, keeping historical events available via recent_alerts. Lacks explicit alternatives or 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns a verdict with structured data, citation, and delta, and notes that it replaces multiple sequential calls, enhancing understanding 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 front-loaded with trigger phrases and structured logically: usage triggers, functionality, domain, return values, performance benefit. It is slightly verbose but each sentence adds value, earning a 4.

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

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

Given no output schema, the description thoroughly explains return values and domain scope. It provides enough information for an agent to decide when to use the tool and what to expect, making it contextually 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 description coverage is 100%, so the baseline is 3. The description provides example claims and clarifies the natural-language format, which adds marginal value but does not significantly surpass what the schema already conveys.

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 begins with clear natural-language trigger phrases and explicitly states what the tool does: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims for US public companies) and distinguishes itself from siblings by describing its unique 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 provides explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and implies domain limitations. It does not explicitly state when not to use or name alternatives, but the context is clear.

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