Lens Org

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds valuable behavioral context beyond annotations: it discloses the exact return structure (per-model {score, confidence, signals, raw_response} + combined view), the free default model, the cost implications of using Anthropic (BYO key), and the ability to probe multiple models. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph of three sentences. It is front-loaded with the core purpose, then details model options and return format. Every sentence adds necessary information without redundancy or verbosity.

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

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

Despite the absence of an output schema, the description fully explains the return structure (per-model fields and combined view). All four parameters are explained in the schema and description. The description covers tool purpose, usage context, model selection, and cost implications, making it complete for an agent to decide when and how to invoke the 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%, so the schema already documents all four parameters. The description adds extra meaning beyond the schema: it clarifies the default model for the 'models' parameter ('Workers AI Llama-3.3-70b (free)') and the purpose of '_apiKey' ('BYO key — you pay Anthropic directly for those calls'). This additional context helps agents understand how to use the parameters effectively.

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

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

The description uses a specific verb ('probe') and clearly defines the resource ('LLMs for knowledge about a business/brand/product/topic') and action ('score visibility 0-100 per model'). It distinguishes itself from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on multi-model probing with scoring and specific model options.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key for Anthropic. However, it does not explicitly describe situations where this tool should not be used, such as when a single answer from one model is sufficient, missing a clear when-not-to-use clause.

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, destructiveHint. Description adds that it routes to 4,552 tools, returns structured answers with citation URIs, works on all tiers, one fast call. 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-structured with clear sections (preference, usage, examples, alternatives). Slightly long but each sentence adds value. Front-loaded with key guidance.

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

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

Given the tool's complexity (6 params, 1 required, no output schema), the description is comprehensive: covers purpose, usage, behavioral details, and examples. No gaps.

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

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

Schema description coverage is 100% with clear alias descriptions. Description adds context that the tool accepts natural language questions, but schema already captures that. Minor extra value.

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

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

The description clearly states 'Routes the question to the right one of 4,552 tools across 1160 verified sources' and distinguishes from siblings like ask_pipeworx_grounded and deep_research, with specific verb-resource pairs and 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?

Explicitly says 'PREFER OVER WEB SEARCH' and provides when to use alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad queries), with concrete examples of query types.

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, destructiveHint=false. The description adds detailed behavioral traits: refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), evidence extraction, return structure, and the extra LLM call cost. 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?

Despite length, every sentence adds value. Structure is front-loaded with purpose, then mechanism, return format, usage guidance, and tradeoff. No wasted words.

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

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

For a tool with no output schema, the description fully covers return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and explains all refusal scenarios. Parameter coverage is complete via schema. No gaps.

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

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

Schema coverage is 100% with 6 parameters all aliases for 'question'. The description does not add meaning beyond the schema, which already documents the aliases. 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 is a 'hallucination-resistant answer mode for high-stakes reads,' specifying the verb (answer), resource (data from 4,552 tools across 1,160 sources), and distinguishes it from ask_pipeworx by explaining the extraction and refusal mechanism.

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

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

Explicitly tells when to use (when answers will be quoted/cited and facts must not be invented) and when to prefer ask_pipeworx ('for casual lookups'), including cost tradeoff ('costs one extra LLM call').

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

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

Annotations provide read-only, open-world, idempotent hints. The description adds extensive behavioral details beyond annotations: resolver contract, parent event extractor, news fields, safety mechanisms (low confidence, closed markets), wide-spread handling, and resolution-rule risk. No contradiction with annotations.

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

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

Very verbose and detailed with labeled sections, which is informative but not concise. While front-loaded with purpose, the length may overwhelm some agents. Shorter summaries 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?

Comprehensively covers input resolving, classification, fan-out logic, response shapes, safety checks, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. With no output schema, the description effectively documents return structure and conditions, making it highly 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%, granting baseline 3. Description explains market input formats, depth enum with default, and include_raw boolean with size implications. This adds meaningful context beyond the schema (e.g., default behavior and use cases for include_raw).

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

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

The description states the tool researches Polymarket bets by pulling Pipeworx data, with clear verbs ('Research', 'Pull', 'Resolve', 'Classify', 'Fan out', 'Return'). It distinguishes itself from siblings like ask_pipeworx and polymarket_edges by focusing on betting research and providing category-specific fan-outs.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides examples and classifiers. However, it does not explicitly mention when not to use or alternatives (e.g., simpler queries might use ask_pipeworx), leaving slight ambiguity.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds rich behavioral detail: for 'company' it describes pulling latest 10-K metrics from SEC EDGAR/XBRL with correct fiscal year handling; for 'drug' it lists FAERS, FDA, trial counts. Also notes result ordering and citation URIs. 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?

Compact yet comprehensive: front-loaded with intuitive query patterns, then concisely covers type-specific behavior, data sources, and output format. Every sentence adds essential information without redundancy.

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

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

Given the moderate complexity (two entity types, multiple data sources) and lack of output schema, the description fully compensates by detailing return format (paired data, citation URIs, sorted by primary metric) and edge cases (off-calendar fiscal years). Complete enough for an agent to understand behavior and expectations.

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

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

Schema coverage is 100%, providing the enum and array details. Description adds meaning by specifying that 'values' are tickers/CIKs for companies or drug names, and clarifies the data sources (10-K, FAERS, etc.) associated with each type. 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?

Description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides example queries like 'compare X and Y' and 'rank these companies'. It clearly distinguishes from sequential single-pack lookups, a sibling tool pattern.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Also clarifies when to use via example queries and lists what each entity type returns, guiding appropriate invocation.

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

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

The description discloses key behavioral traits beyond annotations: account requirement, parallel decomposition, output format (evidence packet with gaps), expected latency (15-60s), and limitations (empty gaps for breaking topics). Annotations already declare safe and idempotent, and description does not contradict.

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 critical information (account requirement and alternative), and each sentence adds value. While slightly verbose, it remains well-structured and informative 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 complexity of the tool (no output schema, but detailed behavioral incentives), the description is remarkably complete. It explains the output format, time expectations, limitations, and use cases, covering all necessary context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with adequate descriptions. The description adds minimal extra meaning, such as the mapping of depth values (quick=3, standard=5, thorough=8). Since the schema already covers the basics, the description provides limited additional 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: grounded multi-source research across Pipeworx's 1160 structured data sources. It uses a specific verb and resource, and distinguishes itself from siblings (e.g., 'this is NOT open-web search', 'for single lookup use ask_pipeworx').

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

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

Explicit when-to-use guidance: best for broad/multi-part questions over structured data. Also provides clear alternatives: ask_pipeworx for single lookup or breaking/news. Additionally, it warns about account requirements and suggests an alternative if not signed in.

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

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

Adds context beyond annotations: explains return format (top-N relevant tools with full schemas and examples), mentions results are ready to call directly without second lookup. 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?

Efficiently structured with front-loaded purpose, usage guidance, return format, and strategic advice. 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?

Provides enough context for a discovery tool: purpose, usage, parameter semantics, output description. Could mention pagination or error handling but not essential for this tool.

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

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

Schema coverage is 100%, baseline 3. Description explains main parameter query as natural language and lists aliases, but does not add significant detail beyond schema. Examples are in schema, not description.

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

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

The description clearly states the tool finds tools by describing data or task, lists supported domains, and distinguishes from siblings by emphasizing its role as a discovery tool.

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

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

Explicitly advises to use when needing to browse or search for tools, and to call it first when many tools are available. Lacks explicit exclusion for when not to use, but provides strong guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable behavioral context: fans out across multiple sources, soft-fails on patents (USPTO sunset), uses GDELT→GNews fallback, and returns specific formatted data.

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

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

The description is front-loaded with example queries, uses a single paragraph, and every sentence adds value—covering data sources, return fields, fallbacks, and constraints 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?

Despite no output schema, the description comprehensively details the returned information: CIK, company name, filings with URIs, fundamentals sorted by period, patents with sunset status, news via fallback, and LEI.

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

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

Schema coverage is 100% with both parameters described. The description adds extra meaning: explains that value can be ticker or zero-padded CIK, warns names not supported, and clarifies type enum currently limited to company.

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

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

The description explicitly states the tool's purpose: generating a full cross-source profile of a US public company. It lists specific data sources and output fields, and distinguishes from siblings by advising preference over chaining individual lookups.

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

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

The description provides clear when-to-use signals via example queries ('tell me about X', 'research Acme'), explicitly states preference over chaining, and warns that names are not supported, directing to resolve_entity as alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but doesn't detail side effects beyond deletion. With annotations covering the destructive nature, the description adds moderate value.

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

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

The description is two sentences plus a helpful pairing hint. Every sentence serves a purpose, and the key action is front-loaded. 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's simplicity (one required parameter, no output schema, clear annotations), the description fully covers purpose, usage guidance, and relationships with sibling tools. No gaps.

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

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

Schema coverage is 100%, so the description's mention of 'by key' adds no extra semantic beyond the schema's property description. 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 verb 'Delete' and the resource 'previously stored memory by key', and distinguishes from siblings by mentioning 'Pair with remember and recall.' This provides specific purpose and differentiation.

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 gives usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also hints at pairing with siblings, providing clear context but no explicit exclusions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. It could mention error handling or rate limits, but overall consistent and informative.

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 followed by a short bullet list of use cases. Every word serves a purpose, no fluff, and the most important information comes first.

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 inputs (2 params) and no output schema, the description explains the process and output format sufficiently. It could address edge cases like large pages or invalid URLs, but it's largely complete 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 descriptions for both parameters. Description adds context: default max_links of 25 and maximum 50, and clarifies the URL should be a full URL. This extra information justifies a score above baseline 3.

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

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

Clearly states it generates an llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. Distinguishes from sibling tools like ai_visibility_check by focusing on outputting the standard file format.

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?

Gives explicit use cases: getting a client's site indexed, drafting your own project's llms.txt, or auditing competitor visibility. Does not define when not to use or list alternatives, but the scenarios are 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 destructiveHint, so the safety profile is covered. The description adds minimal behavioral context by listing return fields and the include_inactive parameter, but does not disclose potential rate limits or other traits. No contradiction.

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

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

The description is two sentences, each earning its place. The first sentence states the purpose and return fields, and the second provides usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no complex output schema), the description is complete. It tells the agent what it does, when to use it, and what it returns. Sibling tools are different enough that no further disambiguation is needed.

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 schema covers 100% of parameters, so the description does not need to add much. It mentions the include_inactive parameter effect, but this is already described in the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool lists the caller's active subscriptions, specifying the verb (list) and resource (subscriptions). It differentiates from sibling tools like subscribe and unsubscribe by clarifying the action.

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

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

The description provides explicit use cases: to review what you're monitoring before adding more or to find an id to cancel. It does not explicitly state when not to use it or mention 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.

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

Annotations already declare readOnlyHint and idempotentHint; the description adds value by specifying the authentication requirement (Bearer token) and the return content ('full bibliographic data including claims, inventors, and priority dates'). No contradiction.

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

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

Single sentence, front-loaded with action and resource, no redundant words. Every part 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 simple single-parameter tool, rich annotations, and presence of output schema, the description provides all necessary context: purpose, input, output scope, and authentication.

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

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

Only one parameter (lens_id) with 0% schema description coverage. The description explains it is used for fetching the record, but does not provide format constraints or examples beyond what is in the schema's example field.

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 'Fetch a single Lens.org patent record by its lens_id', providing a specific verb and resource. It distinguishes from sibling 'patents_search' which likely handles multiple records.

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

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

The description mentions 'requires Bearer token', giving a clear prerequisite. It implies use for single record fetch vs. alternatives like patents_search for multiple results, but does not explicitly state when not to use.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds beyond that by specifying the maximum result count (up to 1000) and the exact fields returned (title, applicant, filing date, claims), providing valuable context about the tool's behavior. 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 a single, concise sentence that packs all essential information: database, query type, auth requirement, result limit, and returned fields. No unnecessary words, well front-loaded with 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 tool's complexity (search with query language, pagination, result fields) and the presence of a comprehensive output schema, the description is nearly complete. It covers the database, authentication, query syntax, result limit, and key fields. The only minor gap is not mentioning pagination parameters ('from', 'size') explicitly, but the schema fills that role.

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 67% with descriptions for 'size' and 'query'. The description adds context to 'query' (free-text or Lucene) and hints at 'size' limit (up to 1000), but does not clarify 'from'. Given moderate coverage, the description provides marginal additional meaning beyond the schema.

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

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

The description clearly states the verb 'search', the resource 'Lens.org patent database', and the method 'free-text or Lucene query'. It also lists the returned fields (title, applicant, filing date, claims), making the tool's purpose unambiguous and distinct from siblings like 'patent' or 'scholarly_search'.

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

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

The description mentions a prerequisite (requires Bearer token) and the query style, but does not explicitly guide when to use this tool over siblings like 'patent' (singular) or 'scholarly_search'. There is no when-not or alternative naming provided, so usage guidance is implicit.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). The description adds critical behavioral details: rate-limited to 5 per identifier per day, free (doesn't count against quota), and that the team reads digests daily and signal affects roadmap. This goes well beyond what annotations provide.

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

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

Description is a concise paragraph of 4 sentences. It is front-loaded with purpose, then usage guidelines, then behavioral notes. No redundant or unnecessary information. Every sentence adds value.

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

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

For a tool with 3 parameters (type, context, message), no output schema, and low complexity, the description fully covers purpose, usage, parameters, and behavioral constraints. It also includes a warning about not pasting prompts. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds limited additional meaning beyond schema: it contextualizes the 'type' enum with examples, and clarifies that 'context' is optional. However, schema itself already provides detailed descriptions for each parameter, including enum 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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific categories (bug, feature, data_gap, praise) and uses a specific verb ('tell'). This tool is distinct from all siblings, which are not feedback-related.

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

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

Explicitly states when to use each category: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides a clear 'don't' instruction about pasting end-user prompts. No alternative tools for feedback, so no comparison needed.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral context: self-aggregating signal, derived from CF analytics-engine, no PII, cached 5min-1h, which are valuable 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 slightly long but well-structured with bullet points and no wasted words. Every sentence adds value, making it efficient despite the length.

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

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

The description covers purpose, usage, behavior, and parameter semantics effectively. It mentions the returned data (top tools, packs, volume) but could be more explicit about the output structure since there is no output schema. Overall, it is nearly 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 enum and description. The description adds additional meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the semantic understanding of the parameter.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window. The verb 'returns' with specific resources and the differentiation from sibling tools like 'discover_tools' makes the purpose unmistakable.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. Caching behavior is noted. No when-not-to-use needed given the read-only, trending nature.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details behaviors like semantic anchor (≥0.30 Jaccard similarity), partition filter (drops placeholder slugs), and fill check against live CLOB depth. It explains that realizable_edge_pp ≤ 0 means the opportunity is not tradeable, adding crucial behavioral context.

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

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

The description is relatively long but well-structured and front-loaded with the core purpose. Each mode is explained in a separate paragraph, and technical details like semantic anchor and partition filter are given after the main explanation. While slightly verbose, every sentence adds value, making it acceptable given the tool's complexity.

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

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

The description fully covers the tool's input options, internal checks, output structure (opportunities[], partition_check), and error conditions (placeholder filter, low similarity). It references sibling tool polymarket_fill_risk for related functionality. Despite the lack of an output schema, the description adequately prepares an AI agent to use the tool effectively.

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

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

The description adds substantial meaning beyond the schema: it explains event slugs (e.g., 'fed-decision-may-2026') and topic seed questions (e.g., 'Strait of Hormuz traffic returns to normal'). It elaborates on how each parameter affects the tool's execution, including the cross-event mode's similarity filter and partition check details.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: trending scan (no args), single-event mode (event slug), and cross-event mode (topic). This specificity and distinction from siblings like polymarket_fill_risk demonstrate excellent purpose clarity.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also notes that cross-event mode captures patterns that single-event misses, and directs users to polymarket_fill_risk for custom sizing, effectively handling alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent. The description adds that the tool is cached 1h at KV level, includes diagnostic counters, and explains that partition arbs return kelly_fraction_half=0 at parent level. No contradictions.

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

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

The description is lengthy but well-structured with numbered segments, bolded terms, and clear grouping. Every sentence adds value, though it could be slightly more concise for quick scanning.

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

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

Despite lacking an output schema, the description thoroughly explains response structure (by_segment, fed_candidates, _diagnostics), edge fields, caching, and knob effects. It covers all necessary aspects for agent invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds context by explaining how knobs like min_kelly and min_liquidity relate to segments and edge realizability, enhancing understanding beyond schema.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with specific model families. It is distinct from siblings like polymarket_arbitrage by focusing on edge detection rather than pure arbitrage.

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

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

The description explicitly frames usage as 'what should I bet on today', explains tradeable-edge knobs, and notes that Fed bets are excluded from ranking. It provides detailed guidance on when to adjust parameters like slippage and filters, though it does not directly compare to polymarket_arbitrage.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds concrete limitations: 60-day snapshot TTL, daily close data, and potential gaps. This provides useful context 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 lengthy (approx. 150 words) and includes detailed response fields. While well-structured, some redundancy (e.g., repeated defaults) could be trimmed. It is adequate but not optimally concise.

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

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

Given no output schema, the description thoroughly documents the response structure (tracked, expired, snapshot_dates) and explains limitations. It is sufficiently complete for a telemetry 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 both parameters described. The description adds default values and options but does not significantly enhance 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 states it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. This differentiates it from sibling tools like polymarket_edges which likely provide current edges.

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

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

The description implies usage through examples (e.g., comparing fresh vs. old edges) but does not explicitly state when to use this tool over others like polymarket_edges or polymarket_arbitrage. Guidance is implicit but not comprehensive.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint), the description adds critical behavioral context: it checks order-book depth, returns fill details and a verdict, and explicitly warns that theoretical overround is not capturable on thin books and that partial basket fills convert an arb into an unhedged directional position. 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 long but well-structured, with mode explanations, return field lists, and a prominent usage warning at the end. Every sentence adds value, though it could be slightly more concise by grouping related return fields. However, it remains highly informative and easy to parse.

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

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

Despite lacking an output schema, the description comprehensively lists all return fields for both modes, including verdict, slippage, fill details, thin_legs, forced_directional_risk, etc. It also provides usage warnings, making the tool's behavior fully understandable for both modes.

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 has 100% description coverage, but the description adds significant meaning: it explains the difference between single-market and basket modes, how size_usd is interpreted differently in each mode, default values, and the relationship between side and auto-detection in basket mode. This goes well 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 opens with a clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes the two modes (single-market and basket) and lists the return fields, making its function unambiguous and distinct from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description ends with an explicit usage directive: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about thin books and partial basket fills, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds rich behavioral context: how spreads are computed, compatibility warnings, temporal alignment, and edge cases like skipped cross types. No contradiction with annotations.

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

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

The description is moderately long but well-organized into logical sections (modes, response, safety fields). Every sentence adds value; no fluff. Could be slightly tighter, but structure aids readability.

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

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

Despite no output schema, the description comprehensively explains the response structure (leg-by-leg prices, spread, safety fields) and covers complex scenarios (temporal alignment, compatibility warnings). It preempts user confusion about why spreads may not exist. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the interaction between parameters (topic vs explicit overrides), listing valid topic values, and providing examples. It goes beyond the schema by clarifying the mode logic.

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 the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison. The verb 'compute' and resource 'spread' are specific, with detailed mode explanation.

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 two usage modes (topic shortcuts vs explicit tickers), explains when to use each, and warns about compatibility issues and temporal alignment. It gives guidance on interpreting safety fields, making it easy for an AI agent to decide when to invoke this tool vs alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by explaining that omitting the key lists all keys and that data is scoped to the agent's identifier. No side effects are mentioned, but it aligns 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 brief (two sentences) and front-loaded with the core action. Every sentence adds value without 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?

Given no output schema, the description explains the two return scenarios (value or list of keys). It could specify the return format (e.g., string vs array), but overall it's adequate for a simple read 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% and the description adds context: 'omit to list all keys' clarifies the optional parameter behavior. It also ties the parameter to the remember action.

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 (retrieve/list), resource (saved values/keys), and distinguishes from sibling tools like remember and forget. It immediately tells the agent what it does and how to use it.

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

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

The description explains when to use (look up context stored earlier) and suggests pairing with remember/forget. However, it does not explicitly state when not to use or list alternative retrieval tools 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?

Despite annotations indicating readOnlyHint and destructiveHint false, the description transparently explains that setting mark_read:true flags events as read, affecting future calls. This side effect is disclosed, adding value beyond annotations.

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

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

The description is concise and front-loaded with the main purpose. Every sentence adds value—purpose, return fields, filtering, mark_read behavior, and alternative endpoint—with no redundancy or fluff.

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

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

With no output schema, the description adequately covers return fields and explains the effect of mark_read. It mentions polling and alternative access, providing sufficient context for a tool with five optional parameters and no required inputs.

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 each parameter. The description summarizes filtering options and provides an example (e.g., 'sec_8k'), but does not add significant new meaning beyond the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies the return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on reading alerts rather than managing subscriptions.

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

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

Provides specific guidance on filtering by type and timestamp, using mark_read for subsequent calls, and mentions polling suitability. It also points to an alternative GET endpoint for scripts/dashboards, helping users decide when to use this tool versus the direct URL.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details fan-out to multiple sources, fallback behavior, error handling (soft-fail for USPTO), and return structure (changes grouped by source, total count, URIs). 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?

Front-loaded with example queries, followed by compact yet comprehensive explanation of behavior, parameters, and alternatives. Every sentence serves a purpose with no redundancy.

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

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

Given the tool has 3 required params, no output schema, and no nested objects, the description fully covers all aspects: data sources, fallback, parameter options, return structure, and sibling distinction.

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

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

Schema coverage is 100%, but the description adds valuable context: explains 'since' accepts ISO or relative shorthand and provides examples (e.g., '7d', '30d'), and clarifies 'type' only supports 'company'. This enhances understanding beyond the schema.

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

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

Description explicitly states it's a change feed for a company in a time window, provides example queries, and distinguishes from sibling tool entity_profile. The verb 'fans out' combined with specific data sources makes purpose very clear.

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 gives clear usage examples and an explicit alternative (entity_profile for static profile). However, it does not fully enumerate when not to use or compare with every sibling.

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 behavioral details beyond annotations: storage scope (key-value pair scoped by identifier), persistence differences between authenticated users (persistent) and anonymous (24-hour retention). Annotations already declare idempotentHint=true, but description adds 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 highly concise (4 sentences) with a clear structure: purpose, usage trigger, storage details, and pairing instructions. Every sentence adds value with 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?

For a simple tool with 2 parameters and no output schema, the description covers purpose, usage context, storage behavior, and pairing with siblings. It is complete given the tool's complexity and the richness of annotations and sibling 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 description coverage is 100% and already explains both parameters well. The description adds example keys (e.g., 'subject_property', 'target_ticker') which clarifies the semantic intent of the key parameter, providing extra guidance 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 the tool's purpose: saving data for later reuse. It specifies the action (save data), the resource (key-value memory), and distinguishes it from sibling tools like 'recall' and 'forget' by mentioning their roles.

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 you discover something worth carrying forward' and 'so you don't have to look it up again'. Mentions pairing with recall and forget, but does not explicitly state when not to use or provide alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive traits. The description adds behavioral details: it cascades through multiple lookup endpoints internally, returning specific data for each entity type (ticker, CIK, RxCUI, etc.). This explains the composite nature 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 paragraph that starts with illustrative queries, states the main purpose, then details supported types and outputs. Every sentence adds value with no redundancy or fluff. It is dense yet clear, fitting within a small space.

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), the description adequately explains return values for both entity types. It mentions internal cascading and citation URIs. While it does not cover error cases or what happens on failure, the coverage is sufficient for a lookup tool with strong annotations.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by giving examples (e.g., 'AAPL', 'ozempic') and clarifying that company input accepts ticker, CIK, or name with auto-disambiguation. This practical usage context enhances the schema definitions.

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

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

The description uses specific examples like 'What's the ticker for...' and clearly states the tool resolves names to canonical IDs. It explicitly lists supported entity types (company, drug) and their outputs. The phrase 'Use FIRST whenever you have a name but need an ID' differentiates it from sibling tools that require IDs as input.

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

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

The description instructs to use this tool first when a name needs conversion to an ID. It covers supported types but does not explicitly mention when not to use it beyond unsupported types. The note about replacing 2-3 manual lookups gives context on efficiency. While not exhaustive, the guidance is clear and actionable.

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, open-world, and idempotent behavior. The description adds value by explaining the probing mechanism with ai_visibility_check, ranking by score, and output details (score, confidence, signal density). No contradictions.

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

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

The description is concise with three sentences covering action, mechanism, and use case. Front-loaded with main purpose, no wasted words.

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

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

For a tool with 4 parameters (1 required) and no output schema, the description fully covers return values (ranked list with score, confidence, signal density) and explains the underlying process. It also gives a practical example, making it 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 good parameter descriptions. The description adds context on how parameters are used together (e.g., entities as first treated as subject) but does not significantly extend individual parameter 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'Compare' and resource 'AI visibility'. It distinguishes itself from the sibling 'ai_visibility_check' by focusing on multiple entities and ranking.

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

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

The description provides a clear use case for competitive AI-marketing audits with an example question. It implies when to use but does not explicitly exclude alternatives like single-entity checks via ai_visibility_check.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral traits: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. 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?

Description is informative and front-loaded with the main purpose. Slightly verbose but necessary given complexity. Efficient for the detail provided.

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

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

With no output schema, description covers return fields (summary block, per-advisory details, links, alternative versions) and error behavior (partial failures). Ecosystem scope and version range are clear. Minor gaps: does not explain 'is_latest' or 'published_at' fields explicitly.

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

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

Schema already covers both parameters with descriptions. Description adds that scoped packages are accepted and version defaults to latest, which is helpful but not essential beyond schema.

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

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

The description clearly defines the tool as a composite check for npm packages, covering license, advisories, version history, and bundle size. It differentiates itself from sibling tools, none of which perform dependency scanning.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small'. Also notes NPM-only scope in v1 and directs to deps.dev for other ecosystems.

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. Description adds what the tool returns (abstract, authors, citations, links), 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?

Single sentence, front-loaded with verb and resource. No unnecessary words, every part contributes 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 (single required param), the description covers purpose, authorization requirement, and return content. Output schema exists, so details on return structure are not needed.

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?

Though schema coverage is 0%, the description explicitly mentions 'lens_id' and ties it to the tool's purpose. It does not provide additional format or constraints, but for a single param, this is sufficient.

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 'Fetch a single Lens.org scholarly work by its lens_id', specifying verb, resource, and identifier. The sibling tool 'scholarly_search' suggests a search alternative, making the distinction clear.

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?

Mentions requirement of a Bearer token, giving a prerequisite. Does not explicitly state when not to use or name alternatives, but the sibling list provides context.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that it requires a Bearer token and that queries can be free-text or Lucene, providing behavioral context beyond annotations. No contradictions.

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

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

The description is a single, efficient sentence that starts with the core action and includes key output details. No unnecessary words or restating of name.

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

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

With an output schema present, the description does not need to detail return values, but it omits pagination, sorting, and descriptions for 'from' and 'size'. The mention of return fields is good, but param coverage is incomplete for a search tool with 3 parameters.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain 'from' or 'size' parameters, though it mentions query type (free-text or Lucene). The examples in the schema are helpful but not part of the description. This leaves significant gaps in parameter understanding.

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

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

Description clearly states it searches Lens.org scholarly works using free-text or Lucene query, and specifies the return fields (title, authors, journal, year, DOI). This is specific and informative, but it does not explicitly differentiate from similar sibling tools like 'scholarly'.

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 requirement of a Bearer token, which is a prerequisite, but it gives no guidance on when to use this tool over alternatives (e.g., 'scholarly' or 'patents_search'). The use case is implied but not explicitly contrasted with 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?

Beyond annotations (readOnlyHint, etc.), the description discloses key behaviors: 200K char truncation with flag, BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, and passage offsets for verification.

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

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

Front-loaded with purpose, then use case, then technical details. Every sentence adds value without redundancy or fluff.

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

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

Covers input cap, output features (passages, offsets, scores), and embedding details. Lacks explicit output structure but given no output schema, the description provides sufficient guidance for understanding expected results.

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 high. Description adds helpful query examples and clarifies the text parameter's truncation behavior, providing richer context than schema alone.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It distinguishes itself from sibling ask_pipeworx_grounded by specifying the pairing workflow.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Also mentions when not to use direct alternatives and pairs with ask_pipeworx_grounded for grounded generation.

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 idempotent, non-destructive, write operation. Description adds account requirements, delivery channel details (email format, SMS verification, webhook signing/auto-disable), and subscription id return, enriching behavioral transparency 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?

Single dense paragraph but well-structured: purpose first, then requirements, types, delivery. Every sentence is informative. Could benefit from bullet points for readability, but remains concise given complexity.

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

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

Covers all necessary aspects for a subscription creation tool: prerequisites, types with params, delivery options, return value (subscription id), and post-subscription behavior (feed always on). No output schema required as return is simple id.

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

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

Despite 100% schema coverage, the description adds substantial meaning: explains each subscription type's params with examples, delivery channel semantics, and constraints (e.g., phone verification, webhook signing). Goes well beyond schema.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a clear verb-resource pair. It distinguishes from siblings like list_subscriptions and unsubscribe, and mentions the return of a subscription 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?

Provides explicit context: requires Pipeworx OAuth account, lists supported types with usage examples. Lacks explicit when-not-to-use guidance versus one-time query tools like polymarket_edges, 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: returns example questions with exact tool+argument shapes, and that it can be called with no arguments or a topic. This enriches the behavioral 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 well-structured with clear sections, including alternative phrasings at the start and a bulleted list of categories. It is slightly verbose but front-loads the purpose and usage. Every sentence contributes meaning.

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

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

Despite lacking an output schema, the description fully explains what is returned (example questions with tool and argument shape) and how to use it (no args or topic). It covers all necessary context for an agent to use this tool effectively.

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

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

Schema coverage is 100% with a detailed description of the 'topic' parameter listing all valid values. The description reiterates the same list but does not add new meaning beyond the schema. Thus the description adds no extra 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 that this tool returns category-bucketed example questions and is the onboarding entry point. It specifies the verb 'returns' and resource 'example questions', and distinguishes from siblings by noting it should be used first to learn about Pipeworx and meta-tools.

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

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

The description explicitly says when to use it: 'the onboarding entry point for an agent that just connected' and 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also implies alternatives (meta-tools) but does not explicitly state when not to use it, which is a minor gap.

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

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

Beyond annotations, describes deactivation behavior and why it's not destructive ('row is deactivated (not deleted) so its historical events stay available via recent_alerts').

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 tight sentences, front-loaded with action, 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?

Fully adequate for a one-parameter tool with good annotations; covers purpose, ownership, and side effects.

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 'id' with schema coverage 100%; description adds minimal value beyond schema by referencing 'subscribe' as source of the id.

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+resource ('Cancel a subscription by id') and distinguishes from sibling 'subscribe'.

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?

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage guidance, though no explicit alternative tools mentioned.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: supported claim types (company-financial), data sources (SEC EDGAR + XBRL), return verdict types, and limitations (v1 for public US companies only).

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

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

The description is somewhat verbose but front-loaded with query examples. Every sentence adds value, though some detail could be more concise. Structure is logical, starting with use cases then specifying domain and return 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 complexity and lack of output schema, the description adequately covers return types (verdict categories, structured form, citation, delta) and context (replaces multi-step process). No major gaps for its domain.

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

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

Schema coverage is 100% for the single parameter. The description adds meaningful context beyond the schema by providing examples and clarifying the natural-language format expected.

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: natural-language claim verification against authoritative sources. It explicitly mentions the domain (company-financial claims) and distinguishes it from sibling tools by noting it replaces multiple sequential calls.

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

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

The description explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and provides domain constraints. It does not explicitly mention when not to use, but the domain focus provides implicit guidance.

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