Gleif

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds behavioral details: default model, BYO key for Anthropic, and return structure. It does not contradict annotations but could mention limitations like model availability.

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 convey purpose, default behavior, optional extension, output format, and use cases. Front-loaded with action verb 'Probe'. 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?

Description covers output format (per-model fields + combined view) and use cases. Lacks explanation of 'signals' field or score computation, but given no output schema, it is fairly complete.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds minimal additional meaning (e.g., default model, key dependency) which is mostly redundant with the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and produces a visibility score per model. It uses a specific verb 'probe' and resource 'LLMs', and distinguishes itself from siblings like 'scan_competitor_ai_presence' by being generic and scoring visibility.

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 enumerates use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not explicitly state when not to use the tool or compare to alternatives such as 'scan_competitor_ai_presence' for specific competitor analysis.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns structured answers with stable citation URIs, routes to thousands of tools, works on all tiers, and is one fast call. No contradictions, and the description provides valuable 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 long but well-structured, with key guidance upfront. Every sentence adds value, though some redundancy could be trimmed. Still effective and front-loaded.

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

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

Given the tool's complexity (4,819 tools, many sources) and no output schema, the description is remarkably complete: it explains what the tool does, how it routes questions, provides examples, usage guidelines, and relationships to sibling tools. Nothing essential is missing.

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. Description explains 'Your question or request in natural language' and lists aliases. While schema already covers meaning, description adds that it accepts natural language, which is helpful. Baseline 3, plus 1 for extra clarity.

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

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

The description clearly states the tool routes questions to 4,819 tools across 1259 sources and returns structured answers with citation URIs. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, with specific examples of use cases.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear guidance on when to use alternatives: 'Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part questions use deep_research; for breaking news it already routes to live news.'

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: describes extraction process, explicit refusal with reasons, and extra cost; no contradiction with readOnlyHint, openWorldHint, etc.

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

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

Front-loaded with key purpose, each sentence adds value; slightly long but efficient for the complexity.

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

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

Covers purpose, usage, behavior, return format, refusal reasons, and cost; annotations cover safety traits; no output schema needed due to described return.

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 aliases documented; description adds no additional semantics beyond listing aliases, so baseline 3 is appropriate.

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

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

Clearly states 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by noting it extracts answers exclusively from tool results.

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 use when answers will be quoted/cited/acted on and facts must not be invented, and recommends ask_pipeworx for casual lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: fan-out to data sources, response shapes with specific fields, resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread tradeability notes, and resolution-rule risk. This goes far beyond annotations, with no contradictions.

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

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

The description is front-loaded with the core purpose but becomes lengthy with detailed examples and edge cases. While every sentence adds value, the sheer length (~600 words) may overwhelm agents. However, the use of all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) provides structure, and the complexity of the tool justifies the length. Still, some sentences could be more terse.

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, the description is remarkably thorough. It covers input types, processing logic (fan-out to category-specific data packs), output structure (market, analysis, evidence, resolver, parent_event, news fields), safety checks (low-confidence, closed markets, wide spreads), and resolution-rule risk. No output schema exists, but the description fully describes the response shape. Everything an agent needs is present.

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

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

Schema coverage is 100% (all 3 parameters described in schema). The description significantly adds value: explains 'market' flexibility (slug, URL, question text), clarifies 'depth' enum (quick vs thorough) with behavior, and details 'include_raw' with size implications and use cases (recompute deltas, cite observations). Examples are also provided.

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 core purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies three input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison), clearly distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on comprehensive per-bet research.

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

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

The description provides explicit use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It also includes safety notes about low-confidence matches and closed markets that implicitly guide when not to rely on the tool. However, it does not directly contrast with alternative sibling tools (e.g., when to use polymarket_edge_tracker instead), missing a clear differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: it pulls from SEC EDGAR/XBRL for companies handling off-calendar fiscal years, and FAERS/FDA for drugs, and explains sorting by primary metric. No contradictions.

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

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

The description is moderately long but every sentence contributes useful information. It front-loads usage examples and ends with an efficiency claim. Minor reduction could combine redundancy but overall efficient.

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

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

No output schema exists, but the description explains return format (paired data with citation URIs) and behavior (sorted by primary metric). It also addresses edge cases (off-calendar fiscal years) and efficiency gain, making it fully informative 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% with basic descriptions. The description enriches parameter meaning by explaining what data each type returns and giving examples (e.g., tickers for companies, drug names). This adds significant value beyond the raw enum and string descriptions.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, listing specific data points (revenue, net income, etc. for companies; adverse-event counts for drugs). It distinguishes from sequential single pack lookups with explicit examples.

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

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

The description provides strong guidance: 'ALWAYS PREFER over sequential single-pack lookups' and lists trigger phrases like 'compare X and Y'. It doesn't explicitly mention when not to use, but the positive 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 indicate read-only, idempotent, non-destructive. Description adds critical behavioral details: account required, paid plan for thorough depth, returns findings packet with verbatim evidence and gaps[], 15-60s response time, and that it returns empty gaps for topics not in structured catalog.

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 somewhat long but front-loaded with essential warnings (account requirement, alternative tool). Each sentence provides distinct value, though some phrasing could be tighter. Structured well with critical info 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?

Despite no output schema, description thoroughly explains the return findings packet and its components. Addresses edge cases (unsupported topics return gaps[]). With only 2 parameters and full coverage, the description makes the tool's behavior and expectations 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% (2 parameters fully described). Description adds context: depth enum explained (quick=3, standard=5, thorough=8 paid), question described as natural language supporting broad/multi-part queries. Provides added value 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?

Clearly states it performs grounded multi-source research across 1259 structured data sources in one call. Distinguishes from sibling ask_pipeworx by noting it decomposes questions into facets and routes to 4,819 tools in parallel.

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

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

Explicitly advises when to use (broad/multi-part questions over structured data) and when to avoid (breaking news, colloquial topics). Provides alternative ask_pipeworx for single lookups and news. Also mentions account requirement and depth tiers.

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 valuable behavioral details: it returns top-N most relevant tools with full input schemas and examples, and mentions it accepts multiple aliases for the query parameter. 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 concise (4-5 sentences) and well-structured: first sentence states the purpose, second lists domains, third explains the return value, and fourth provides usage guidance. Every sentence adds essential information 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?

Despite the absence of an output schema, the description fully explains what the tool returns (top-N relevant tools with names, descriptions, and full input schemas with curated examples). Given the tool's simplicity and the richness of annotations and input schema, the description is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description further adds meaning by listing the aliases (q, task, search, description) and explaining that the query is a natural language description. The examples in the schema enhance understanding, making the parameter semantics exceptionally clear.

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: to find tools by describing the data or task. It provides specific examples of domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself from sibling tools by advising to call it first when many tools are available, making 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?

The description gives explicit guidance on when to use the tool ('when you need to browse, search, look up, or discover what tools exist') and when to call it first ('Call this FIRST when you have many tools available and want to see the option set'). It also implies when not to use it (if you already know the specific tool), providing clear context and alternatives.

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

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

Descriptions adds significant behavioral context beyond annotations: it explains the multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), details return fields (cik, filings with URIs, fundamentals sorted), and notes the patent soft-fail. Annotations already declare readOnly, openWorld, idempotent, non-destructive, which the 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 information-dense but not overly verbose. It starts with usage examples and a clear purpose, then lists return data. Every sentence adds value. Slightly long but well-organized.

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?

Complex tool with no output schema, yet description covers: input types, return fields with details (URIs, sorting, fallbacks), limitations (patent sunset, name restriction), and comparison to alternatives. This is fully adequate for an agent to understand and 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?

Input schema has 100% description coverage. The description restates the schema (type='company', value=ticker/CIK) and adds small extra context (zero-padded CIK, names not supported). Given high schema coverage, baseline is 3; the added value is marginal.

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 provides a 'full cross-source profile of a US public company in ONE parallel call' and uses concrete examples like 'Tell me about X' and 'research Acme'. It clearly distinguishes from chaining single-pack lookups and specifies supported entity types (company only).

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 advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, recommending use of resolve_entity first. This provides explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description confirms the destructive action ('delete') but adds no additional behavioral context 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?

Two concise sentences with no wasted words. Front-loaded with the core action and followed by usage guidance.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and relationship to siblings completely.

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

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

The input schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete'. The description adds no additional parameter information beyond the schema.

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

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

The description clearly states the tool deletes a memory by key, using specific verb 'delete' and resource 'memory'. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

The description provides clear use cases: stale context, task completion, clearing sensitive data. It implicitly guides when not to use by specifying these scenarios, and suggests pairing with related tools.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds functional details: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This goes beyond annotations by explaining the operational steps and output format, though it could mention potential rate limits or dependencies.

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

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

The description is concise: two sentences plus a bulleted list of use cases. It front-loads the main action and output, then lists applications. Every sentence adds value without redundancy, making it easy for an agent to quickly understand the tool.

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 params, no output schema, no nested objects), the description covers all necessary aspects: what it does, how it works, the output format, and concrete use cases. Since the output schema is absent, the description compensates by explicitly describing the output as 'standard llms.txt markdown format' and 'ready to drop at site-root/llms.txt'.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about the tool's behavior (e.g., 'Fetches the page, extracts title/description/key links') but does not provide additional parameter-specific details beyond what the schema offers. The use cases indirectly relate to the url parameter but no further semantic enrichment.

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: to generate a production-ready llms.txt file for any URL. It specifies the verb 'generate' and the resource 'llms.txt file', with explicit mention of its use by AI crawlers. This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on visibility auditing rather than file generation.

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: getting a client's site indexed, drafting for own project, or auditing competitor AI presence. While it does not mention when not to use the tool or directly name alternatives, the listed scenarios offer clear guidance on appropriate contexts, making it better than average.

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 value by listing the returned fields, but does not discuss potential errors (e.g., invalid LEI) or rate limits. With strong annotations, the bar is lower, so a 4 is appropriate.

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 concise sentences with front-loaded action. Every sentence adds value: first states purpose, second lists return fields. 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?

For a simple one-parameter tool with an output schema, the description covers the key details. It could mention error cases (e.g., non-existent LEI) but is generally complete. Annotations fill in safety/behavioral context.

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

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

Schema coverage is 100%, and the description restates '20-character LEI code' without adding extra meaning such as format validation or case sensitivity. Baseline of 3 is correct.

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

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

The description clearly states the action ('Fetch') and the resource ('full Level 1 LEI record'), distinguishing it from siblings like 'get_lei_relationships' and 'search_lei'. It also enumerates the specific fields returned, which helps the agent understand the scope.

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

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

The description implies use when needing a full LEI record by code, but it does not explicitly contrast with siblings like 'search_lei' (for searching by name) or 'get_lei_relationships' (for relationships). No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint; description adds that it fetches specifically 'Level 2' hierarchy (depth constraint). No contradiction with annotations.

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

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

Two efficient sentences: first states function and specifics, second gives use case. 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 low complexity (1 param, output schema exists), description adequately covers purpose and usage. Could mention return format or pagination, but output schema likely handles that.

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

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

Schema coverage is 100%, and the description does not add significant meaning beyond the schema's '20-character LEI code' description. The brief mention of 'LEI' in context is redundant.

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 action ('Fetch'), resource ('Level 2 corporate hierarchy for an LEI'), and specific components ('direct parent, ultimate parent, and direct children'). It distinguishes from siblings like 'get_lei' (basic LEI data) by specifying the hierarchy output.

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

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

Provides explicit usage context: 'Use to map ownership trees across multinational groups.' However, it does not mention when not to use or list alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns specific fields and can optionally include inactive subscriptions, providing behavioral context beyond the annotations.

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

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

Two sentences: first states the core function with return fields, second gives usage guidance. Front-loaded and 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 simple list tool with no output schema and only one optional parameter, the description fully covers what the agent needs: what it does, what it returns, and when to use it. Annotations complete the safety profile.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning to the 'include_inactive' parameter beyond the schema's description. No extra value 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 uses specific verb 'List' and resource 'the caller's active subscriptions', and returns specific fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This helps the agent decide between this and other subscription-related tools.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily with signals affecting roadmap. 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?

Every sentence earns its place: purpose, use cases, guidance, behavior, and rate limits. Zero waste and front-loaded with the core 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?

For a feedback tool with no output schema, the description is fully complete. It covers all necessary usage context, parameter guidance, and behavioral notes. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds value beyond schema by instructing how to fill the message (e.g., 'describe the issue in terms of Pipeworx tools/packs') and reinforcing the type enum meanings. Slightly 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?

The description starts with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the verb (tell), resource (Pipeworx team), and scope (feedback on issues or improvements). It distinguishes from all siblings by being the only feedback 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 defines when to use: '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 what not to do: 'don't paste the end-user's prompt' and to describe in terms of Pipeworx tools/packs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: derived from analytics-engine, no PII, caching 5min-1h, self-aggregating signal. No contradiction with annotations.

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

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

Description is three sentences plus a bullet list, front-loaded with main function. Every sentence adds value without redundancy. Concise and well-structured.

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

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

The tool is simple with one optional parameter and no output schema. The description explains return structure ('top tools, top packs, total call volume') and includes data sources and caching. It could specify ranking criteria (e.g., by call count) but is otherwise complete for a read-only aggregation 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 complete description for the only parameter 'window'. The main description does not add new parameter information beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Returns' and resource 'top tools, top packs, total call volume', clearly stating the tool's purpose. It distinguishes from sibling tools by focusing on aggregate trending data of agent calls, not individual queries.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case) providing clear context for when to use. Does not explicitly state when not to use or alternatives, but the use cases are specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe. The description goes far beyond by detailing algorithms (Jaccard similarity filter, partition filter, fill check against live CLOB depth), response structure, and edge cases (placeholder slugs, overround at last-trade vs book). 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 detailed but verbose, containing algorithm explanations that might be excessive for an AI agent. It is front-loaded with the core purpose and mode guidance, but the technical depth could be streamlined for better conciseness.

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

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

Given the tool's complexity (2 optional params, no output schema), the description is remarkably complete. It explains all behavioral aspects: mode selection, semantic anchor, partition filter, fill check, response structure, and references to companion tools. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: it explains the two parameter modes with examples, clarifies that event is recommended for specific markets, and describes the behavior difference between event and topic modes. This elevates the score above baseline.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args (trending_scan), event (single-event), and topic (cross-event). It also differentiates from sibling tool 'polymarket_fill_risk' for custom sizing.

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 guides when to use each parameter (event for specific market, topic for cross-event scan, no args for trending scan). It recommends event mode and mentions alternatives like polymarket_fill_risk for custom sizing. However, it does not explicitly contrast with other siblings like polymarket_edges.

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, and non-destructive hints. The description adds deep behavioral context: caching (1h KV-level), diagnostic fields, filter logic, and edge calculation details. No contradiction with annotations.

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

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

The description is very long but well-structured with sections and front-loaded purpose. It could be slightly more concise, but the structure aids readability and every sentence adds value.

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

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

Given 9 parameters, rich behavior, and no output schema, the description fully covers return structure (three segments with diagnostics), filtering, and caching. It is comprehensive for an agent to use correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds substantial meaning: explains defaults, examples, edge cases (e.g., min_partition_leg_kelly vs min_kelly), and tradeable-edge filter rationale. This goes well beyond the mere 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 Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes itself from siblings by detailing its segments and knobs.

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 extensive context on when to use the tool (discovering opportunities without paging) and explains the segments and knobs. However, it does not explicitly exclude alternatives or directly contrast with sibling tools, so it lacks explicit 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?

The description discloses detailed behavioral traits: returns tracked[], expired[], and snapshot_dates[] with specific fields; explains limits (60-day TTL, daily closes not intraday). This adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.), and there is no contradiction with annotations.

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

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

The description is well-structured: it starts with the core purpose, then details the response structure, and ends with limits. While it is somewhat verbose, every sentence adds value. It could be slightly more concise, but it remains clear and front-loaded.

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

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

Given the complexity (no output schema, 2 optional parameters), the description fully covers the response format (tracked with time-series, trend, decay; expired with lifespan; snapshot_dates with gaps) and constraints (TTL, gap reasons, decay calculation). It is complete for an AI agent to use correctly.

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

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

Both parameters ('days' and 'window') have clear descriptions in the schema (100% coverage). The description further adds meaning by explaining the default values, valid ranges, and options for 'window' (24hr, 1wk, 1mo), plus clarifies that 'days' is a lookback. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and is distinct from sibling tools like polymarket_edges (raw data) and polymarket_arbitrage (arbitrage opportunities).

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

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

The description explicitly states the use case: determining how long an edge has existed and if it is shrinking. It provides context on why fresh vs old edges matter. However, it does not explicitly state when NOT to use this tool or mention alternatives among siblings, 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?

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which are consistent with the description. The description adds rich behavioral context: walking the order book ladder, returning fields like slippage, shares filled, verdict, and warning about forced directional risk, going well beyond the annotations.

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

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

The description is somewhat lengthy but well-structured with clear sections for single-market and basket modes, bolded warnings, and a summary sentence. Every sentence adds value, though minor trimming could improve conciseness without losing information.

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

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

Given the tool's complexity (two modes, multiple return fields), the description is highly complete. It lists all key return fields for both modes, explains the 'thin_legs' and 'forced_directional_risk', and warns about the dominant loss mode. No output schema exists, but the description compensates thoroughly.

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 all four parameters described. The description adds extra meaning, such as how size_usd is interpreted differently for single-market vs basket mode, and the auto-detection of side for baskets. This provides valuable semantic context beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It uses specific verbs and resources, and is well-differentiated from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risks of partial fills and unhedged directional positions, clearly stating when this tool should be used over alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds rich behavioral details: compatibility_warning triggers, temporal alignment checks, and skipped_cross counters. 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 longer than typical but well-organized with headings (TWO MODES, RESPONSE, SAFETY FIELDS). No redundant sentences; each part adds value. Slightly lengthy given the tool's complexity, but not excessive.

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

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

Despite no output schema, the description covers response structure (leg prices, top_spreads_pp), safety fields, and caveats. For a 3-param read-only tool with high schema coverage, this is fully 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 descriptions for each parameter. The description adds significant context: lists all 10 topic shortcuts, explains mode behavior, and clarifies parameter overrides. This exceeds baseline.

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

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

The description clearly states the tool computes the spread between two venues for the same question, differentiating it from siblings like polymarket_arbitrage which is single-venue. It uses specific verbs ('Cross-venue spread') and describes the core function.

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

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

Explicitly explains two modes (topic shortcuts vs explicit tickers) and provides strong caveats about when spreads are meaningful vs when compatibility warnings fire. Warns that pre-mapped topics often return warnings, setting clear usage expectations.

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 significant context: scoping to user identifier and the dual behavior (retrieve vs. list). This goes beyond the annotations, though no additional constraints like rate limits are mentioned.

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

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

The description is concise and well-structured: it states the primary action, provides a usage example, explains the scope, and mentions paired tools. 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 tool with no output schema, the description adequately explains what it does (retrieve value or list keys). However, it does not explicitly describe the return format or examples of output, which would increase completeness for an agent.

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

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

Schema coverage is 100%, so the schema already documents the one parameter. The description echoes the schema's description for 'key' and adds context on omission behavior, but does not significantly enhance the semantic meaning beyond what the schema provides.

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

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

The description uses a specific verb ('Retrieve') and resource ('value previously saved via remember'). It explicitly distinguishes the tool from siblings by mentioning pairing with remember and forget, and specifies two modes: retrieving by key or listing all keys.

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

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

The description clearly states when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and how to list all keys. It implicitly differentiates from remember and forget, but does not explicitly exclude other use cases or mention alternatives beyond the immediate sibling pair.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the mark_read parameter's stateful behavior (flagging events as read) and that polling is supported. 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 that front-loads the purpose. It is concise with no unnecessary words. While it could benefit from bullet points for clarity, it efficiently conveys all necessary information.

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

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

Given the tool's complexity (5 optional parameters, no output schema), the description adequately covers the return fields (source, citation_uri, raw payload), the effect of parameters, and pollability. It does not detail pagination or error handling, but for a read-only tool with strong annotations, this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds meaningful context beyond the schema: it explains that 'type' filters to one subscription type, 'since' is an ISO timestamp for minimum fired_at, 'mark_read' flags returned events as read, and 'unread_only' returns only unread events. This combination of parameters and their interplay is clarified.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the resource (subscription feed) and the action (pull/returns), and it distinguishes itself from siblings like list_subscriptions and subscribe/unsubscribe by focusing on alert events.

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

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

The description provides usage context: it mentions optional filtering by type and timestamp, and notes that polling works fine. It also offers an alternative access method (GET endpoint). However, it does not explicitly state when to use this tool versus other related tools, such as list_subscriptions or search_within.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds details: fans out to multiple sources, has fallback logic, soft-fails for USPTO, and returns structured changes[] with citation URIs. Adds significant 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?

Description is detailed but well-structured with front-loaded examples. While slightly lengthy, every sentence adds value. Could be slightly more concise, but overall effective.

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

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

Despite no output schema, the description explains return structure (changes grouped by source, total_changes, citation URIs). Covers usage scenarios, sources, fallbacks, and parameter details. Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds meaning: explains 'since' accepts ISO date or relative shorthand, suggests using '30d' or '1m', clarifies 'value' can be ticker or CIK, and notes 'type' only supports 'company'. Enhances understanding.

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

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

The description clearly states it provides a change feed for a company over a time window, with example queries like 'What's new with X'. It distinguishes from sibling tool 'entity_profile' which is for static profiles.

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 this tool (change feed) and when to use 'entity_profile' instead. Also explains fallback behavior between GDELT and GNews, and provides parameter guidance like suggesting '30d' for typical monitoring.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context beyond annotations: scoping by identifier, persistence differences between authenticated and anonymous users, and the 24-hour retention limit for anonymous sessions.

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

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

The description is three sentences with no wasted words. It front-loads the main purpose and quickly provides actionable context, scope, and companion tools. Every sentence contributes meaningful information.

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

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

For a simple write-side tool with no output schema, the description covers all essential aspects: purpose, when to use, storage behavior, and pairing with sibling tools. It is fully adequate for effective selection and 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 covers 100% of parameters with clear descriptions. The description adds marginal value by framing the parameters as key-value pairs with examples, but does not provide additional semantic detail beyond what the schema already offers.

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

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

The description uses specific verbs ('save', 'retrieve', 'delete') and clearly states the resource ('data the agent will need to reuse later'). It distinguishes from siblings by naming 'recall' and 'forget' as companion tools, providing clear 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 states when to use ('when you discover something worth carrying forward') and provides context for scope ('across this conversation or across sessions'). It also names alternative tools ('recall', 'forget') for related operations.

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 non-destructive. The description adds valuable behavioral details: internal cascading through multiple endpoints, auto-disambiguation, and specific return data per type including citation URIs. No contradictions.

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

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

The description is well-structured, starting with example queries and purpose, then detailing types. It is slightly long but each sentence adds value, so it earns its space. Could be slightly more concise but still effective.

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

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

Given no output schema, the description fully explains return values for both entity types, including citation URIs and auto-disambiguation. It also notes the cascading internal behavior, making the tool's operation transparent and complete for an agent to use correctly.

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

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

Schema has 100% coverage with descriptions for both parameters. The description enriches semantics by explaining what each entity type returns, how input variations are handled (ticker, CIK, name for company; brand or generic for drug), and the role of auto-disambiguation.

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

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

The description uses specific verbs ('resolve', 'look up') and clearly identifies the resource (canonical/official identifiers). It distinguishes its purpose from sibling tools like entity_profile by stating it is the first step when needing an ID from a name.

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 FIRST whenever you have a name but need an ID', giving clear context for when to use. It lacks explicit when-not-to-use scenarios, but the provided context and supported types make its scope 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 safe, idempotent, non-destructive behavior. The description adds that it probes each entity and ranks results, but does not elaborate on side effects or edge cases beyond that. Consistent with annotations.

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

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

Three sentences, front-loaded with purpose, no filler. Every sentence adds value: purpose, method, use case, 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 no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density). Input parameters are fully described in schema. Annotations cover safety. Complete for a read-only comparison tool.

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

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

Schema coverage is 100%, so the description adds meaning beyond schema especially for the 'entities' parameter, noting that the first entity is treated as the 'subject' for narrative. The description also explains the purpose of the 'context' parameter implicitly.

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, uses ai_visibility_check internally, and produces a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility domain.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use this over ai_visibility_check (multi-entity comparison) but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds behavioral context about partial failures (bundlephobia timeout 5-30s, sources_failed list), graceful degradation, and that it fans out across sources. 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 dense with useful information but somewhat long (200+ words). Front-loaded with main purpose, each sentence adds value. Minor verbosity, but efficient for 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?

Despite no output schema, the description fully explains the return format (summary block, per-advisory detail, links, alternative versions). Covers multiple data sources, partial failures, and ecosystem constraints. Complete for a composite tool.

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

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

Schema coverage is 100% with good descriptions. The description adds meaning for the 'package' parameter by noting scoped packages are accepted. For 'version', it clarifies default behavior (latest when omitted). Adds some extra context beyond schema.

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

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

The description clearly states the tool is a composite check for npm packages aggregating data from deps.dev and bundlephobia, with a specific use case ('should I add this npm package to my project'). It distinguishes from siblings by noting NPM ecosystem only, with other ecosystems under deps.dev:version.

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 agent asks about safety, popularity, size) and when not (non-NPM ecosystems). Provides alternative tool reference (deps.dev:version 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 (readOnlyHint, openWorldHint, idempotentHint) already convey key behavioral traits. The description adds return field details but no additional behavioral context like rate limits or pagination. It does not contradict annotations.

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

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

Two concise sentences: first states action and output, second states use case. No superfluous text; 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?

With output schema present, description needn't detail return values. Parameters fully documented in schema. Description provides sufficient context for use without 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?

Parameter schema covers all four parameters with descriptions. The tool description mentions return fields but does not add meaning beyond schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool searches the GLEIF LEI registry by legal entity name and returns specific fields (LEI, jurisdiction, status, cross-references). It distinguishes from sibling tools like get_lei, which retrieves a single LEI, by indicating search functionality.

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

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

The description provides clear context for using the returned LEI to resolve canonical identity across databases, implying when to use this tool. However, it does not explicitly state when not to use it or contrast with alternatives beyond the implicit role of the LEI.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' 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 dense paragraph that front-loads the purpose. Every sentence adds value: purpose, use case, output details, pairing info, and technical implementation. No wasted words.

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

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

Despite no output schema, the description explains the output (top-N passages with offsets and similarity scores), the embedding model, truncation behavior, and limit. The tool's functionality is fully covered for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (e.g., text is from a fetched record, examples for query) and reinforces limit default/range. It doesn't add new param details beyond schema but provides useful supplementary context.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document fetching.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and mentions saving context. It doesn't provide explicit when-not-to-use or all alternatives, but the context is clear and alternatives are implied.

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

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

The description adds behavioral details beyond annotations, such as account requirements, delivery limits (10/day cap for SMS), webhook auto-disable after 10 failures, and type-specific parameters. However, it does not clarify if the tool is idempotent despite the annotation hint.

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 and front-loaded with the core purpose. It provides necessary details without extraneous information, maintaining conciseness while covering requirements and examples.

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 account requirements, return value, type-specific parameters, and delivery options. It lacks explicit error handling or response structure details, but given the absence of an output schema, it is sufficient for an agent to use the tool correctly.

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

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

The description enriches the schema with concrete examples for each subscription type (e.g., 'items:["5.02"] = officer change') and delivery constraints (e.g., phone verification required). Schema coverage is 100%, so the description adds significant meaning beyond the property descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies that a Pipeworx OAuth account is required and gives examples for each subscription type. It does not explicitly compare to alternatives but provides context for when to use each type.

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, idempotent, non-destructive. Description adds context: returns example questions with tool arguments, drawn from a live catalog. 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 somewhat lengthy but front-loaded with key phrases. Each sentence adds value, though slight condensation is possible.

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 (1 optional param, no output schema), the description fully covers its purpose, usage, and output structure.

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

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

Schema coverage is 100% with description for 'topic'. Description elaborates with examples ('finance', 'pharma') and semantics of focusing the output.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns') and resources ('example questions') and distinguishes from siblings by focusing on learning what Pipeworx can do.

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 guidance to use this tool first when unsure of Pipeworx capabilities or to learn meta-tools. Mentions optional topic parameter but does not explicitly state when not to use it.

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

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

Goes beyond annotations: explains that the row is deactivated (not deleted) and historical events remain via 'recent_alerts'. Provides ownership enforcement detail. Annotations already indicate idempotent and non-destructive, but description adds valuable 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?

Three sentences, front-loaded with action. No redundant information. Efficient and to the point.

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

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

Complete for a simple tool with one parameter and no output schema. Covers purpose, ownership, behavioral effect (deactivation vs deletion), and relationship to historical data.

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

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

Schema has 100% coverage with description for the single parameter 'id' (Subscription id (uuid) returned by subscribe). Description does not add further semantics beyond what schema provides, meeting baseline for high coverage.

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

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

Description clearly states 'Cancel a subscription by id', which is a specific verb-resource action. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and method.

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', which guides when to use. Also notes id is returned by 'subscribe', providing context. Does not explicitly compare to alternatives but implied.

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, open-world, non-destructive behavior. Description adds domain details, return format (verdict, structured form, citation, delta), and limitations (v1 scope). 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 informative but slightly verbose. However, it is well-structured with examples first, then usage, then details. Could be trimmed slightly without loss.

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 single-param tool with no output schema, the description thoroughly explains the return value and domain constraints. It covers all necessary context for correct invocation.

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

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

Schema coverage is 100% with a solid description. The description adds example queries but does not significantly extend beyond the schema's parameter description. 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's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides multiple example queries and distinguishes itself from siblings by noting it replaces 4-6 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?

Explicitly advises use for fact-checking claims, with a domain restriction to company-financial claims for public US companies. Does not explicitly state when to avoid, but the scope is well-defined.

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