Ror

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the match is fuzzy and returns confidence scores, which complements the annotations without contradiction.

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

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

Two short sentences with no redundant information. Every word serves a purpose, making it efficient and front-loaded.

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

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

For a simple tool with one parameter and an output schema, the description covers purpose and output adequately. No missing information needed 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 0%, so description must compensate. It clarifies that 'text' is an affiliation string for fuzzy matching, which adds meaning beyond the schema. However, it does not detail format or constraints beyond schema examples.

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

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

The description uses specific verbs ('match') and resource ('affiliation-string'), and specifies output ('candidates with confidence scores'). It clearly distinguishes from siblings like 'resolve_entity' by focusing on fuzzy matching of affiliation strings.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies it's for affiliation matching but does not provide exclusions or comparisons to 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it reveals that probing is free for Workers AI, that Anthropic calls require a BYO key and direct payment, and describes the return structure (per-model scores, confidence, signals, raw_response, combined view). 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 three sentences, front-loaded with core purpose and score range. Each sentence adds a distinct element: function, model options, output and use cases. No redundant or extraneous information.

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

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

With 4 parameters and no output schema, the description covers purpose, parameters (with examples and rationale), output structure (per-model + combined view), and use cases. It is complete for an agent to understand how to invoke the tool correctly and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining why you'd use _apiKey (BYO key, direct payment to Anthropic) and context helps disambiguate. It provides examples for entity and clarifies the default model. This adds significant value.

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

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

The description uses a specific verb 'probe' and resource 'LLMs for visibility', clearly defining the tool's action. It distinguishes from siblings by mentioning AI-marketing audits, pre-launch checks, and competitive monitoring, which sets it apart from tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the default model versus adding Anthropic with an API key. While it does not directly contrast with siblings or provide exclusion criteria, the context is sufficiently clear for agent decision-making.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that the tool routes questions to 3,745 tools across 884 sources and returns structured answers with stable citation URIs, providing useful behavioral 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 concise, front-loaded with the key guidance to prefer over web search, and uses bullet-like lists of domains and examples. Every sentence serves a purpose without repetition.

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

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

The description fully covers the tool's purpose, usage context, return format (structured answer with citations), and provides multiple examples. Despite no output schema, the description adequately informs the agent of what to expect.

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

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

Schema coverage is 100% with descriptions of the 'question' parameter and its aliases. The description supplements with example queries in the text, helping the agent understand how to phrase questions, which adds value beyond the schema.

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

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

The description clearly states the tool is for factual queries about current or historical data, listing many specific domains. It distinguishes from web search but does not explicitly differentiate from its sibling 'ask_pipeworx_grounded', though the context implies this is the primary 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 says 'PREFER OVER WEB SEARCH' and gives concrete examples of when to use, such as for unemployment rates, SEC filings, etc. It advises using even when web search could answer, making the usage guidance very 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?

Provides extensive behavioral context beyond annotations: details extraction process, returns refusal reasons on failure, explicitly states it costs one extra LLM call. Annotations already indicate readOnly/idempotent, but description adds critical usage constraints.

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

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

Single dense paragraph that front-loads the core purpose and then details behavior, return format, and use case. Efficient but slightly long; every sentence provides 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?

Comprehensively covers input, output, success/refusal cases, and cost implication. No output schema but description fully specifies the return structure with example fields.

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 descriptions. Description adds context that the question parameter is used to route to tools and fill arguments, but all parameter aliases are already documented in schema. Marginal additional value.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers strictly from tool results, distinguishing it from the sibling 'ask_pipeworx' which is for casual lookups.

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

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

Explicitly states when to use the tool (when answers will be quoted, cited, or acted on, and must not invent facts) and when to prefer the sibling 'ask_pipeworx' (casual lookups), including a cost trade-off.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds extensive behavioral detail: market resolution, classifier fan-out per category, response shapes, resolver contract, parent event extraction, news fallback, and cancellation rules. No contradictions.

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

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

The description is comprehensive but verbose, with many inline examples and explanatory notes that could be condensed. While well-organized with section headings, it may require careful parsing by an agent, risking information overload.

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

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

Despite no output schema, the description thoroughly covers return structure (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields), safety mechanisms, and edge cases. All critical aspects are addressed 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%, so parameters are documented structurally. Description adds value by explaining market input types, depth enum with default, and include_raw usage policy. This enhances usability beyond the schema alone.

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

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

The description states a specific verb ('Research') and resource ('Polymarket bet'), details input types (slug, URL, question text), and distinguishes itself by returning an evidence packet and comparison. It clearly separates from sibling tools like polymarket_edges by focusing on data assembly for a specific bet.

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

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

Explicit usage scenarios are given ('Use for "should I bet on X"...'). Includes safety conditions (low-confidence short-circuit, closed markets) that guide when to trust results. However, no direct comparison to alternatives like validate_claim, though context suggests this tool is for data-rich research.

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, etc. The description adds valuable context: it discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, and mentions sorted output and citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with the purpose and example phrases, but it is somewhat verbose. Each sentence adds value, but it could be condensed slightly. Still, it is well-structured and informative.

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

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

Given the tool has only 2 parameters and no output schema, the description provides comprehensive context: tool purpose, when to use, data sources, sorting behavior, return format (paired data + URIs). It fully supports agent decision-making 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 coverage is 100% (both parameters described). The description adds meaning by explaining that 'type' determines the data source and that 'values' should be tickers/CIKs for companies or drug names. It provides examples like ['AAPL','MSFT'] and ['ozempic','mounjaro'], enhancing schema detail.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single call. It provides specific verbs ('compare', 'vs', 'rank') and distinguishes from sibling tools like entity_profile by emphasizing that it replaces multiple sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives detailed guidance for each type (company vs drug), including what data is pulled (10-K revenue for companies, FAERS counts for drugs) and how results are sorted.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds details: returns explicit gaps[], facts are never invented, requires account, paid plan for thorough depth. 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, starting with the core function, then process, output format, usage hints, requirements, and timing. No unnecessary sentences.

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 the return value structure (findings packet with evidence, confidence, source, citation, gaps[], time). It gives all needed context for tool selection and use.

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

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

Schema covers both parameters (100% coverage). Description adds context for 'depth' values (quick=3, standard=5, thorough=8) and links thorough to paid plans, which is useful 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 performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools. It distinguishes itself from siblings like ask_pipeworx by noting it handles broad/multi-part questions.

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

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

Explicit guidance is provided: 'Use for broad or multi-part questions... use ask_pipeworx for single lookups.' It also mentions requirements (Pipeworx account, paid plan for depth:thorough) and expected time (15-60s).

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. Description adds value by explaining the return format (top-N tools with names, descriptions, full input schemas with curated examples, ready to call directly), which is 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?

Description is somewhat long (4 sentences) but front-loaded with purpose and usage. Every sentence adds value, though could be slightly more concise without losing completeness.

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 meta-tool with full schema coverage and clear annotations, the description covers the essence: what it returns, when to use it. No output schema, but description explains return content sufficiently.

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

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

Schema coverage is 100% with all parameters described, including aliases. Description adds minimal extra meaning beyond the schema, just emphasizes 'natural language description' and gives examples, but the schema already has examples.

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

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

The description clearly states it finds tools by describing data or task, listing many domains. It distinguishes from sibling tools by being a meta-tool for discovering other tools, not returning data itself.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. Provides strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields (e.g., recent_filings with URIs, fundamentals sorted), mentions patent API sunset and soft-fail behavior, and explains input constraints. 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 relatively long (12+ sentences) with some redundancy (e.g., 'names not supported' appears twice). It is front-loaded with example queries and structured explanations, but could be more concise. Every sentence provides useful information, but the overall length reduces skimmability.

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

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

Despite lacking an output schema, the description thoroughly explains the return format: specific fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patent info, news fallback, LEI), data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), and edge cases (USPTO sunset soft-fail, name unsupported). It provides sufficient context for correct invocation. Minor gap: no indication of response size or rate limits.

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

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

Schema coverage is 100% with both parameters described. The description significantly enhances meaning: it provides concrete examples (e.g., 'ticker "AAPL" or zero-padded CIK "0000320193"'), explains that names are not supported (repeated twice for emphasis), and clarifies that the type parameter is currently limited to 'company.' This goes well beyond the schema's brief descriptions.

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

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

The description starts with concrete query examples ('Tell me about X', 'research Acme'), then states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with 'chaining single-pack SEC/XBRL/news lookups,' showing differentiation from siblings. The purpose is specific and unambiguous.

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

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

The description says 'ALWAYS PREFER over chaining ... when the user asks for a holistic view,' providing clear when-to-use guidance. It also states that names are not supported and advises using resolve_entity first, giving a clear alternative. However, it lacks explicit when-not-to-use scenarios.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the core behavior. The description adds context about clearing sensitive data but does not discuss idempotency or failure modes.

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 are concise and front-loaded. The first sentence states the action, the second provides usage guidance and pairing. Every sentence adds value.

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

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

Given the simple parameter and annotations, the description covers purpose and usage well. It does not explain behavior on missing keys or confirmation responses, but these are minor omissions.

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

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

Schema description coverage is 100% and the schema parameter description already states 'Memory key to delete'. The tool description only adds 'by key', providing minimal additional meaning.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by its destructive nature.

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

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

The description explicitly lists three use cases: when context is stale, task is done, or clearing sensitive data. It also pairs with remember and recall, giving clear guidance on when to use.

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

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

Describes actual steps: fetches the page, extracts title/description/key links, emits markdown. Annotations already indicate readOnly, idempotent, non-destructive; description adds behavioral 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?

Two succinct sentences plus bulleted use cases. Front-loaded with purpose, every sentence serves a purpose with no redundancy.

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

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

Despite no output schema, description clarifies output format (llms.txt markdown blob) and placement. Covers behavior, output, and audience comprehensively for a simple tool with rich annotations.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. Description adds default value for max_links (25, max 50) which matches schema but doesn't significantly augment parameter meaning.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, targeting AI crawlers. It specifies the output format and distinguishes itself from sibling tools, which are unrelated (e.g., search, affiliation).

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 (client indexing, personal project drafting, competitor auditing) providing clear context. No when-not-to-use or alternative tools mentioned, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by explaining that the tool accepts both a trailing identifier and full URL, which clarifies input flexibility beyond the schema.

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

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

Single sentence that is concise and front-loaded with the main purpose. No extraneous information; every word earns its place.

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

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

For a simple fetch tool with an output schema (not shown but present), the description is adequate. It could mention the return format slightly, but the annotations provide sufficient safety context. Slightly more detail on using the exact identifier format would improve completeness.

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

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

The input schema has 0% description coverage for the ror_id parameter, but the description explicitly defines its semantics: it can be either a trailing identifier or a full URL. This fully compensates for the missing schema description.

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

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

Clearly states the tool retrieves a full ROR record, specifying that it accepts either a trailing identifier or full URL. This distinguishes it from sibling tools like search or resolve_entity which have different scopes.

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

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

No guidance on when to use this tool versus alternatives such as search or resolve_entity. The description does not mention prerequisites, limitations, or exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds return fields and default behavior (active only), complementing annotations without contradiction.

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

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

Two sentences, first states purpose and returns, second gives usage. No wasted words, front-loaded with key info.

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 parameterless tool with one optional parameter, description lists return fields and gives usage context, fully adequate for 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 coverage is 100%, description does not add extra meaning beyond the parameter description in the schema but implies it by stating 'active subscriptions'.

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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It is clear when to use, though doesn't explicitly state when not to use.

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

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

Annotations indicate the tool writes but is not destructive. The description adds context: it's free, doesn't count against quota, and is rate-limited to 5 per identifier per day. No contradiction with annotations.

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

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

The description is concise yet comprehensive, front-loading the purpose and use cases in two sentences with 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?

Despite lacking an output schema, the description explains the outcome (team reads digests, signal affects roadmap) and the rate limit, making it complete for a feedback tool.

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

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

Schema description coverage is 100%, so the parameters are well-documented there. The description reinforces the enum types but doesn't add significant new semantic meaning beyond the schema.

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

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

The title and description clearly convey the tool's purpose: sending feedback to Pipeworx about bugs, features, or praise. It is distinct from sibling tools which serve other functions like search or entity 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?

The description specifies exactly when to use the tool (bug, feature, data_gap, praise) and includes important guidance like not pasting user prompts and noting rate limits. This helps the agent decide appropriately.

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?

Describes aggregation source (CF analytics-engine), data privacy (no PII), and caching behavior (5min-1h). Annotations already declare readOnlyHint, so this adds valuable behavioral 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?

Four sentences, front-loaded with purpose, then use cases, then behavioral details. No filler; 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 simple tool with one optional parameter, good annotations, and no output schema, description fully covers return values, aggregation, caching, and privacy. No gaps.

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

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

Schema covers the single parameter with description; description adds nuance about window meanings: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond schema.

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

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

Description clearly states verb 'Returns' and resource 'top tools, top packs, and total call volume' over a window. The phrase 'What other AI agents are calling on Pipeworx right now' is specific and distinguishes it from sibling search/research tools.

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

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

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment). However, does not mention when not to use or alternatives, though the context is clear.

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

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

Beyond annotations, the description details the algorithmic approach (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filtering, and fill check against CLOB depth. No contradiction with readOnlyHint=true as tool only analyzes.

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 critical requirement and provides dense, valuable information. However, it is somewhat lengthy and could be structured with bullet points for easier scanning. All sentences are justified but verbosity slightly reduces 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?

Covers modes, algorithm, filters, and fill check. Without output schema, it describes response fields adequately. Marginally complete—could include more explicit output structure, but given complexity, it serves well.

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

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

Adds significant meaning beyond schema: explains accepted formats for 'event' (slug or full URL), provides examples for 'topic', and describes how each parameter drives the mode. Schema coverage is 100% but description enriches semantics substantially.

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 two modes (single-event vs cross-event) and references sibling tools 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?

Explicitly states requirement of one of 'event' or 'topic', recommends event mode for specific markets and topic for cross-event scanning, and references polymorphic_fill_risk for custom sizing. Includes examples and notes failure on no args.

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, and not destructive. The description adds extensive behavioral context: caching (1h KV-level), response segmentation (by_segment, fed_candidates, _diagnostics), edge calculation details (e.g., Kelly fractions, slippage, 24h-move warning), and filter logic. This far exceeds what annotations provide.

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

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

The description is front-loaded with a clear purpose statement and well-organized sections (model families, knobs, response structure). While long, each sentence adds substantive detail relevant to the tool's complex functionality. Minor redundancy could be trimmed, but overall it earns its length.

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

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

Given the absence of an output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), all fields (edge_pp_net, kelly_fraction, market metrics, warnings), and caching behavior. It also explains edge cases like Fed bets and empty segments, ensuring the agent understands the complete context.

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

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

Schema coverage is 100% with detailed descriptions, so baseline is 3. The description adds value by grouping parameters into 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and explaining their conceptual role, which enhances understanding beyond individual parameter definitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies it's for 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on cross-referencing internal data with market prices.

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

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

The description explicitly frames the tool as 'Built for what should I bet on today' and implies it avoids paging hundreds of markets. However, it does not provide explicit when-to-use or when-not-to-use guidance relative to siblings like polymarket_arbitrage or polymarket_edge_tracker, though the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds rich behavioral context: it details the decay computation (on absolute edge_pp_net), return structure (tracked, expired, snapshot_dates), data generation conditions (cache-miss), and limitations (daily closes only). 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 dense and front-loaded with the core purpose. It packs multiple pieces of information (return fields, limits, data gaps) into a single paragraph. While not bulleted, it is efficient and every sentence adds value, though a slightly more structured format could improve readability.

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

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

Despite no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their meanings. It also covers limitations (60-day TTL, cache-miss gaps) and data freshness. For a complex tool, the description is complete enough for correct usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds defaults (14 days, 1wk window) and explains how days and window affect the snapshots. It also provides response semantics, clarifying the output structure, which 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 begins with a specific verb-resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers what the tool does—tracking how long an edge has existed and if it is shrinking—and implicitly distinguishes it from sibling polymarket_edges (which likely provides raw edges).

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

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

The description explains the use case: differentiating between a fresh wide edge and an old wide edge. It mentions limits (60-day TTL) but does not explicitly state when not to use the tool or list alternatives. However, the sibling context and implied contrast with polymarket_edges provide sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and for basket mode details thin_legs, forced_directional_risk, and the risk of partial fills. No contradiction with annotations.

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

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

The description is long but well-structured: purpose sentence first, then mode-specific explanations, then usage guidance. It is front-loaded with the core purpose. While slightly verbose, it is necessary to cover the complexity of two modes and multiple return fields.

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 lists all return fields for both modes, covers prerequisites, usage context, and associated risks. For a tool with 4 parameters and two modes, this is complete and leaves no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the two modes, which parameters are required for each, how size_usd is interpreted differently (spend vs target proceeds vs settlement notional), and default side logic for basket mode. This significantly enriches 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource. It distinguishes two modes (single-market and basket) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by noting it should be used before acting on their signals.

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

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

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

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich behavioral context: compatibility_warning conditions, temporal alignment, skipped cross-type/subtype counters, and the note that real spreads are rarer than shortcuts suggest. 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?

Description is fairly long but each sentence serves a purpose. Front-loaded with core purpose and modes, then response details, then safety field explanations. Some redundancy in examples but overall effective. Could be slightly trimmed but still 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?

No output schema, so description bears full burden of explaining return values. It covers leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skipped counters. For a complex tool with multiple failure modes, the description is thorough and 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% (all 3 parameters documented). Description adds value by explaining the two modes, listing pre-mapped topics, and describing override behavior. Provides examples in schema but description further clarifies semantics, justifying 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 clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It explains the concept of spread and differentiates by mentioning two modes and providing examples, which helps distinguish from sibling tools like polymarket_arbitrage.

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

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

Explicit guidance on when to use topic shortcuts vs explicit tickers, including a warning that most pre-mapped topics return compatibility_warning. Also explains conditions under which spreads are not meaningful via safety fields, covering when-not-to-use scenarios.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: behavior when key omitted, scoping to identifier, and pairing with remember/forget. No contradictions.

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

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

Two efficient sentences, front-loaded with action, no wasted words. Every sentence adds value: function, use case, scope, and pairing.

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 simple input (one optional param) and no output schema, description sufficiently covers retrieval behavior and scoping. Lack of return format or error handling is acceptable for such a simple tool.

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

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

Schema coverage is 100% with one parameter described. Description adds meaning: 'omit to list all keys' and links to remember. This goes beyond the basic schema description.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools remember and forget.

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

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

Explicitly states when to use: to look up context stored earlier, and when to omit key: to list all. Names alternative tools (remember, forget) and provides scoping context.

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

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

The description adds value beyond annotations by explaining the returned data structure (source, citation_uri, raw payload), the effect of mark_read, and that polling works fine. Annotations already cover safety traits, but the description provides useful behavioral context.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no redundancy.

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

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

Given no output schema, the description adequately explains the return values (source, citation_uri, raw payload). It also covers filtering, polling suitability, and an alternative access method, making it complete for this relatively simple 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?

With 100% schema description coverage, the description enhances parameter understanding by providing examples (e.g., type 'sec_8k'), clarifying the 'since' parameter as ISO timestamp, and explaining the effect of mark_read on subsequent calls.

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 pulls fired events from the subscription feed and returns recent alerts with specific fields. However, it does not explicitly differentiate this tool from siblings like 'list_subscriptions' or 'subscribe', which may have overlapping 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 implies usage by showing filtering options and mentions polling, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it 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?

Beyond annotations (readOnly, idempotent, openWorld), the description reveals that the tool fans out to multiple sources in parallel, details the logic (GDELT preferred, GNews on failure), and mentions a known sunset limitation for USPTO. This provides rich behavioral context that helps an agent understand the tool's side effects and data sources.

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

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

The description is relatively long but every sentence contributes useful information. It is structured with example queries first, then source explanations, parameter details, return format, and a sibling alternative. It could be slightly more concise, but the structure aids readability.

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

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

Despite no output schema, the description thoroughly covers return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also explains the fallback mechanism, source limitations (USPTO sunset), and the parallel fan-out nature. For a tool with three parameters and complex behavior, this provides a complete picture.

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

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

Since schema description coverage is 100%, the baseline is 3. The description adds value by explaining the 'since' parameter's accepted formats (ISO date or relative shorthand) with examples like '7d', '30d', '1y', and suggests typical usage ('Use '30d' or '1m' for typical monitoring'). This goes beyond the schema's basic description.

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

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

The description clearly defines the tool as a change feed for companies over a time window, with multiple concrete example queries like 'what's new with X' and 'updates on Acme'. It distinguishes from sibling 'entity_profile' by specifying that 'changes' vs 'static profile' is the differentiator.

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 the tool (for temporal change queries) and provides a direct alternative ('Use entity_profile instead when you want the static profile'). It also explains the fallback behavior between GDELT and GNews, though it does not explicitly list all scenarios where this tool should be avoided.

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

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

Adds rich context beyond annotations: key-value scoping by identifier, persistence differences for authenticated vs anonymous users, and 24-hour TTL. No contradiction with annotations.

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

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

Front-loaded with purpose, then usage, then behavioral details. Each sentence provides distinct 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?

Fully explains when, what, how, and related tools. Persistence model and pairing with recall/forget make the tool unambiguous 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?

Input schema covers both parameters with 100% description coverage. The description repeats the same examples, adding no new semantic information.

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

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

The description clearly states the verb 'Save' and the resource 'data', specifying reuse across conversations/sessions. It distinguishes from sibling tools 'recall' and 'forget' by directly mentioning pairing.

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

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

Explicitly tells when to use (discovering something worth carrying forward) and gives concrete examples. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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, destructiveHint=false) are consistent. The description adds context about internal cascading lookups and that it replaces 2-3 manual steps, enhancing transparency beyond annotations without contradiction.

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

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

The description is dense with valuable information but slightly verbose. It front-loads the primary use case, then covers supported types and return details. Each sentence contributes, but could be trimmed slightly without loss of clarity.

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 details return values and behavior for both entity types. It covers input possibilities, auto-disambiguation, and internal complexity, enabling an agent to correctly invoke and interpret results 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?

Schema coverage is 100%, but the description adds rich semantics: enumerates exact return fields per type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand for drug), explains auto-disambiguation for company, and maps input values to output behavior. This goes far beyond schema descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples ('ticker', 'CIK', 'RxCUI') and explicitly contrasts with siblings by positioning it as a first-step lookup tool.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also differentiates the two supported types with detailed return information, eliminating ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it probes each entity with ai_visibility_check and ranks, which is useful process info. 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?

Three concise sentences, front-loaded with purpose, no wasted words.

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

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

Covers input (entities, optional models/api key/context), process (probes, ranks), output (ranked list with score/confidence/signal density). Missing potential error handling or dependency on ai_visibility_check, but sufficient for a tool with good annotations.

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

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

Schema description coverage is 100%, including the same detail about first entity being subject. Description does not add new parameter semantics beyond schema.

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

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

Clearly states it compares AI visibility across entities side-by-side, using ai_visibility_check, ranking results. Distinguishes from sibling 'ai_visibility_check' by being a comparative 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 states use case: competitive AI-marketing audits, with concrete example. Does not explicitly mention when not to use (e.g., single entity) but context is clear.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds behavioral details: fans out to deps.dev and bundlephobia, lists return fields, mentions potential delays (5-30s) for bundlephobia first measurement, and graceful degradation.

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 somewhat long. It front-loads the main purpose and each sentence adds value, though it could be slightly more concise.

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

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

Despite no output schema, the description thoroughly explains the return structure (summary block fields, per-advisory detail, links, alternative versions) and covers all key aspects of the tool's behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context like accepting scoped packages for 'package' and default version behavior for 'version'.

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

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

The description clearly states that it performs a composite check for adding an npm package, covering licenses, advisories, bundle size, etc. It answers questions like 'is X safe/popular/small' and distinguishes itself from sibling tools which are unrelated.

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

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

Explicitly states when to use: 'whenever an agent asks ...'. Also notes that it's NPM-specific and that other ecosystems fall under different tools, and describes partial failure behavior.

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 clearly mark the tool as read-only and idempotent, but the description adds no behavioral context beyond the schema. It does not mention pagination, result limits, or output format, which is acceptable given the output schema exists, but still leaves gaps.

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

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

The description is extremely concise with a single sentence. No wasted words, but could be improved by adding a bit more context without becoming verbose.

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

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

Given that schema covers all parameters and output schema exists, the description is minimal but covers the essential purpose. However, it lacks context on when to use and how results are returned, making it just adequate.

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

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

Input schema coverage is 100%, so all parameters have descriptions. The tool description adds no additional parameter meaning, so it scores the baseline of 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 explicitly states the verb ('Search') and resource ('organizations'), making the primary purpose clear. However, it does not differentiate from sibling tools like 'search_within' or 'deep_research', which could cause confusion.

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

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

No guidance on when to use this tool vs. others. The description does not explain prerequisites, limitations, or scenarios where alternatives like 'search_within' or 'deep_research' would be preferred.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation flag, and output includes character offsets and similarity scores. 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 somewhat long but front-loaded with the core purpose. Every sentence adds useful information (embedding details, truncation, pairing with another tool). It could be slightly more concise, but there is no redundancy.

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

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

Given moderate complexity and no output schema, the description compensates by explaining what the tool returns (passages with offsets and scores) and its limitations (200K char cap, truncation). It also provides usage context (pairing with ask_pipeworx_grounded), making the definition complete 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% with descriptions for all three parameters. The description adds value by explaining that 'text' is the document to search, 'query' is a natural-language question with examples, and 'limit' controls max passages. This goes beyond the schema's basic 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 tool name 'search_within' and description clearly state it performs semantic search inside a fetched record. The verb 'search' and resource 'text inside a record' are explicit. The description distinguishes it from siblings by mentioning pairing with ask_pipeworx_grounded, making its unique role clear.

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

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

The description explicitly advises using this tool when the record is too large to fit in the prompt, saving context. It also mentions pairing with ask_pipeworx_grounded as an alternative workflow. However, it does not explicitly list when not to use it or compare to all 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?

The description adds significant behavioral context beyond the annotations, including OAuth requirement, type-specific parameters, delivery channel constraints (phone verification, 10/day SMS cap, webhook auto-disable), and the fact that webhook signing secret is returned once. The annotations indicate non-read-only, non-destructive, and idempotent behavior, which is consistent.

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

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

The description is information-dense and well-structured, starting with the purpose and return value, then covering subscription types and delivery options. It could be slightly more concise, but every sentence adds value.

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

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

Given the complexity (nested objects, multiple types) and no output schema, the description covers return value (subscription id), authentication, rate limits, and error scenarios (webhook auto-disable). It lacks explicit error handling for subscription creation failures, but 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?

With 100% schema coverage, the description still adds substantial meaning to each parameter. It provides type-specific examples for the 'params' object (e.g., sec_8k items array, polymarket_edge topic) and detailed constraints for delivery channels (e.g., SMS verification, webhook HMAC signing).

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb (create) and resource (subscription), and it distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear usage context, including the requirement for a Pipeworx OAuth account and examples of supported subscription types with parameters. However, it does not explicitly state when not to use this tool or compare it to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe read behavior. Description adds that it returns live catalog examples with exact tool+argument shapes, which is beyond what annotations provide.

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

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

Description is front-loaded with common trigger phrases, then states purpose and details. It is relatively long but every sentence adds value. Minor redundancy could be trimmed 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?

Despite lacking an output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shape). For a simple tool with one optional param, it provides complete contextual information.

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

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

Schema coverage is 100% with a single optional topic parameter described. Description adds value by explaining default behavior ('full spread') and examples of valid topics like 'finance' or 'pharma', which enhances usability beyond schema.

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

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

Description clearly states the tool returns category-bucketed example questions to help new users understand what to ask Pipeworx. It uses specific verbs and distinguishes its role as the onboarding entry point from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly instructs to use this tool FIRST when the agent does not know what Pipeworx can do, and to learn how to call meta-tools. Also notes optional topic parameter for focus, providing clear when-to-use context.

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

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

Adds context beyond annotations: the unsubscribe deactivates rather than deletes, keeping historical events available. Annotations already indicate idempotent and non-destructive, and description aligns and elaborates.

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

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

Two concise sentences front-loading the purpose and adding key behavioral detail. No superfluous words.

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

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

For a single-parameter tool with no output schema and complete annotations, the description covers all necessary context: action, ownership, and side effects.

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

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

Schema description coverage is 100% for the single parameter 'id'. The description does not add additional meaning beyond 'by id' and ownership context, but the schema already sufficiently describes the parameter.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from siblings like subscribe, list_subscriptions, and recent_alerts.

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?

Explains ownership enforcement and that the row is only deactivated, not deleted. Implicitly guides when to use (cancel own subscription) but lacks explicit mention of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: returns verdict categories (confirmed, refuted, etc.), extracted structured form, actual value with citation, and percent delta. Also discloses data sources (SEC EDGAR + XBRL). 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 front-loaded with purpose and trigger phrases, then covers usage, domain, and return fields. It is somewhat lengthy but every sentence adds value. Could be slightly more concise, but overall well-structured.

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

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

For a tool with one simple parameter and no output schema, the description is fairly complete. It explains the verification domain, data sources, verdict types, and return fields. It also highlights the benefit of replacing multiple calls. However, it could explicitly mention that it only covers US public companies and financial claims.

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

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

Only one parameter (claim) with 100% schema description coverage. The schema already provides examples. The description reinforces the claim format and adds domain context but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger phrases ("Is it true that…", "fact check", etc.) and distinguishes itself by being a specialized claim verification tool among diverse siblings like search, recall, etc.

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 to use whenever the agent needs to check factual correctness of a user's statement. It specifies the domain (company-financial claims) and mentions it replaces 4–6 sequential calls, implying it's the preferred method. Lacks explicit when-not-to-use but domain limitation serves as implicit guidance.

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