Edmtrain

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

The description adds behavioral detail beyond annotations: it notes the default model is free, that passing _apiKey incurs costs via Anthropic, and the return format. Annotations already indicate read-only and idempotent, so the description complements 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 four sentences, with the main action in the first sentence. It is front-loaded, concise, and contains no unnecessary words. Every sentence provides essential information.

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

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

Despite having no output schema, the description fully explains the return format (per-model score, confidence, signals, raw_response, plus combined view). It covers parameters, use cases, and behavior, making it complete for a tool with 4 parameters and no output schema.

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

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

Schema coverage is 100%, and the description adds value by clarifying the default model for 'models' parameter, the role of '_apiKey' (BYO key, direct payment), and the purpose of 'context' (disambiguation). The description enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: to probe LLMs for brand visibility and score it. The verb 'probe' and resource 'LLMs' are specific, and the output 'score' is defined. It distinguishes from siblings like scan_competitor_ai_presence by focusing on general visibility scoring rather than competitor-specific analysis.

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

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

The description provides clear context for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model and BYO key for Anthropic but does not explicitly exclude or compare to alternatives like scan_competitor_ai_presence. The guidance is good but not exhaustive.

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. Description adds context about routing to 5,008 tools and returning citation URIs, which is beyond annotations. No contradictions.

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

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

Front-loaded with key instruction to prefer over web search. While verbose with multiple examples, every sentence adds value. Could be slightly more concise but well-structured.

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

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

Covers purpose, usage guidelines, behavioral context, parameter examples, and alternatives. No output schema exists, but description mentions return format (structured answer with citation URIs). Complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds usage examples but doesn't provide additional meaning beyond the schema for the parameters. The aliases are listed in schema.

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

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

The description clearly states it routes questions to authoritative structured data sources, with many examples. It explicitly prefers this over web search for factual queries, distinguishing it from siblings like web search or other pipeworx 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?

Provides explicit when-to-use (factual questions about real-world entities), when-not-to-use (hallucination-resistant needs use ask_pipeworx_grounded; broad/multi-part use deep_research), and examples of appropriate queries.

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 behavioral details: fallback behavior ('Falls back to nothing'), experimental status, and source-preference ranking mechanism. This goes beyond annotations, though it could disclose more about output handling.

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, well-structured paragraph that efficiently conveys purpose, usage, and experimental nature. Every sentence adds value without redundancy.

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

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

Given no output schema and the tool's role as a router, the description explains key aspects: identical to ask_pipeworx with experimental routing, source-preference behavior, and fallback. Lacks output format details but references 'same response shape' as stable router, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific meaning beyond noting aliases for the question field. The mention of source-preference ranking relates to usage, not parameter values.

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

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

The description clearly states it's a beta version of ask_pipeworx, a universal router with experimental routing improvements. It specifies the verb+resource ('universal router') and distinguishes from siblings like ask_pipeworx by noting 'newest routing' and 'experimental edge.'

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 it 'exactly like ask_pipeworx when you want the newest routing' and implies it's for testing. Provides context on source-preference ranking but does not fully exclude alternative use cases or compare with other siblings like ask_pipeworx_grounded.

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

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

Annotations already declare readOnly, idempotent, non-destructive; description adds that it returns a structured refusal on failure, picks the right tool from 5008, and costs an extra LLM call, which no annotation covers.

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

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

The description is moderately long but each sentence adds essential context. Could be slightly tighter, but 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 complexity (grounded extraction, multiple tool routing, structured output), the description covers purpose, behavior, return shape, and refusal reasons. Lacks details on confidence scale or evidence length, but sufficient for selection.

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% as all 6 parameters are aliases for 'question'. Description merely restates that they are aliases, adding no new semantic value beyond the schema.

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

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

The description clearly states it is a hallucination-resistant, grounded answer mode for high-stakes reads. It distinguishes from sibling ask_pipeworx by specifying the extra cost and strict extraction behavior.

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

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

Explicitly states when to use (high-stakes quotes, cited answers) and when to prefer ask_pipeworx (casual lookups), providing clear decision guidance.

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

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

The description adds extensive behavioral context beyond annotations, including market resolution, classifier fan-out, safety short-circuits for low-confidence matches, closed market handling, spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is extremely verbose (over 500 words) with dense examples, classifier lists, and response shapes. While front-loaded with the purpose, it lacks structural clarity (e.g., sections, bullet points) and includes excessive detail that could be in schema or examples.

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

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

Despite no output schema, the description comprehensively covers input, process, output shapes (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and resolution rules, making it fully informative 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?

All three parameters have schema descriptions (100% coverage), and the tool description adds significant value by explaining how 'market' accepts slugs, URLs, or question text; depth options; and include_raw guidance on when to use true/false.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific input types and output. It lacks explicit sibling differentiation, though sibling tools like polymarket_edges serve different purposes.

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

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

The description provides clear use cases (e.g., 'should I bet on X', 'what does the data say about Y') but does not list when not to use the tool or mention alternatives like polymarket_edge_tracker for ongoing edge tracking.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with URIs. No contradictions. Minor gap: no mention of error handling or rate limits, but these are less critical given the read-only, idempotent nature.

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

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

The description is a single dense paragraph that front-loads example phrasings and the core action. Every sentence adds value and there is no redundancy. However, it is somewhat long (100+ words) and could be slightly more structured (e.g., separating type-specific details). Still, it is efficient and clear.

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

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

Given the tool's complexity (two entity types, multiple data sources, output format), the description provides comprehensive context. It covers what data is returned (paired data, citation URIs), sorting behavior, and efficiency gains. No output schema exists, but the description compensates by describing the return structure. Minor omissions: no mention of pagination or exact field names, but these are not critical for a comparison tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema descriptions. For 'type', it explains the specific data pulled per entity type and how fiscal years are handled. For 'values', it provides example formats (tickers/CIKs for companies, drug names) and clarifies range (2-5). This greatly aids agent understanding of parameter usage.

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. It uses specific verbs and resources ('compare', 'pulls', 'returns paired data') and explicitly distinguishes from sequential lookups (e.g., entity_profile) by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. The example phrasings further clarify intent.

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

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

The description gives explicit when-to-use guidance with example user phrasings ('X vs Y', 'which is bigger', 'rank these companies'). It strongly recommends preferring this tool over sequential lookups, stating it replaces 8-15 calls. It does not provide when-not-to-use or alternatives explicitly, but the context from sibling tools and the clear preference statement suffice for strong guidance.

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

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

Disclosures include account requirements, paid plan limitation, parallel tool routing, output format with evidence/gaps/contradictions, hop fields, citation URIs, semantic excerpting, and time estimates. All beyond the readOnlyHint annotation, 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?

Description is comprehensive but slightly lengthy. However, it is well-structured with logical sections and no wasted sentences, so it earns a high score despite 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?

All necessary context is provided: prerequisites, usage comparisons, parameter details, behavioral traits, output format, and timing. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100%, and the description adds significant value: explains depth enum values (quick=3, standard=5, thorough=8) and advises using broad questions for effective decomposition.

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

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

The description explicitly states the tool performs grounded multi-source research across structured data sources in one call, and distinguishes itself from sibling tools like ask_pipeworx. It uses specific verbs and resource description.

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

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

Provides clear when-to-use vs alternatives: for single lookup use ask_pipeworx, for breaking news prefer ask_pipeworx, and mentions account requirements. Also gives example queries suitable for this tool.

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 idempotentHint=true, matching the non-destructive nature. The description adds behavioral detail: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is front-loaded with the central purpose and usage guidance. Every sentence adds value: examples, limitations, and return details. It is dense but well-structured, though slightly longer than strictly necessary.

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 compensates by detailing the return format (top-N tools with schemas and examples). It covers discovery needs adequately but could mention sorting/relevance criteria. Overall, it is complete for its purpose.

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

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

Schema coverage is 100%, and the description adds meaningful context for the key parameter 'query' by providing natural language examples and listing aliases (task, q, description, search). The 'limit' parameter is also explained. The description enhances the schema's baseline 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 states 'Find tools by describing the data or task' with a specific verb and resource. It provides a detailed list of domains (SEC filings, financials, FDA drugs, etc.) and positions itself as a discovery tool, clearly distinguishing from sibling tools that are more specific (e.g., ask_pipeworx, deep_research).

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when to use but does not explicitly exclude cases where a specific tool is known. Alternatives are not named directly, but the discovery 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 (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), the description adds significant behavioral context: it fans out across multiple sources, returns specific fields including URIs, notes the USPTO sunset and soft-fail, and mentions it returns in one parallel call. 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 front-loaded with example queries and key points. It is informative but slightly lengthy; there is some redundancy (e.g., 'names not supported' appears twice). However, it earns its length by providing essential details.

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

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

Despite no output schema, the description fully explains the return fields: cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. It also addresses caveats like patent soft-fail and name resolution. This provides complete context for an agent to use the tool.

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

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

With 100% schema description coverage, the description adds meaning beyond the schema: it clarifies that type is only 'company' for now, and value must be ticker or zero-padded CIK (explicitly saying names not supported). This helps the agent avoid errors.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides example queries and lists the data sources and return fields. It distinguishes from chaining single-pack lookups by saying 'ALWAYS PREFER over chaining...'

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

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

The description explicitly says when to use this tool: 'ALWAYS PREFER over chaining single-pack...' and when not to: 'names not supported (use resolve_entity first if you only have a name).' It also notes that only 'company' type is supported, setting clear boundaries.

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 the tool as readonly, idempotent, and non-destructive. The description adds behavioral details like the ~75 mile radius for lat/long and the relationship between parameters. It could be improved by mentioning return format or pagination, but it is adequate.

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

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

The description is a single concise paragraph that front-loads the core purpose. Every sentence adds value, with 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?

The tool has 9 optional parameters and no output schema; the description covers input semantics well but does not describe return values or pagination. Given the complexity and annotations, it is nearly complete but missing output details.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains region specification via lat/long vs location_ids, the ~75 mile radius, and that location_ids come from a separate tool. This goes beyond mere 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 finds upcoming electronic/dance events, concerts, and festivals. It specifies the resource ('events') and verb ('find'), and distinguishes from sibling tools by focusing on electronic/dance music events.

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

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

The description provides clear guidance: specify a region via latitude+longitude or location_ids, and optionally filter by date, name, or festivals. It does not explicitly state when not to use the tool, but the context is clear and no alternatives are provided among siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the behavioral context of deleting stored data and clearing sensitive data. There is no contradiction, and the description enriches understanding beyond annotations.

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

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

The description is extremely concise with three sentences: purpose, usage guidelines, and related tools. It is front-loaded and every sentence adds value without redundancy.

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

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

For a simple tool with one parameter, full schema coverage, and informative annotations, the description is complete. It covers purpose, usage scenarios, and relationships with other tools. The lack of output schema or additional complexity makes this sufficient.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description simply reiterates 'by key' without adding new semantic meaning. Baseline score is appropriate as the description provides no additional parameter details.

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

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

The description states 'Delete a previously stored memory by key', which is a specific verb and resource. It clearly distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion, while the others store and retrieve respectively.

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

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

The description provides explicit when-to-use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', guiding the agent on related tools. However, it lacks explicit when-not-to-use guidance.

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

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

The description adds behavioral context beyond annotations: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the fetch operation and output format, complementing the readOnlyHint and idempotentHint annotations. No contradictions.

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

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

The description is three sentences long, each focused and valuable. The first sentence states the primary function, the second outlines the process, and the third lists use cases. No wasted words.

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

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

Despite lacking an output schema, the description clearly states the output is 'a single text blob ready to drop at site-root/llms.txt,' which is sufficient for an agent to understand the return value. It covers the process and expected format. Minor improvement could mention error handling 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?

The input schema already fully describes both parameters (url and max_links) with 100% coverage. The description does not add new information about parameter meaning or constraints, staying at the baseline for schema-rich tools.

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 specifies the tool's purpose with a clear verb-resource pair: 'Generate a production-ready llms.txt file for any URL'. It elaborates on the intended outcome (indexing by AI crawlers) and differentiates from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description lists three explicit use cases: getting a client's site indexed, drafting for own project, and auditing competitors. However, it does not provide guidance on when NOT to use the tool or suggest alternatives among the sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds that only active subscriptions are returned by default and mentions the include_inactive parameter, which is helpful 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 sentences, no wasted words, front-loaded with purpose and key details. Efficient and clear.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers all necessary aspects: what it does, what it returns, and when to use it.

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 well-described boolean parameter. Description does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the tool lists active subscriptions, specifies returned fields (id, type, params, created_at, last_fired_at, fire_count), and is distinct from siblings 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?

Directs when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it could more explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it lists specific fields and covers EDMtrain metros, but does not disclose additional behavioral traits like rate limits or pagination. With strong annotations, this is adequate.

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 with no wasted words. Front-loaded with purpose and immediately useful usage guidance.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, and how to combine with events. Missing explicit return format, but it's not critical given output fields are listed.

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

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

Schema coverage is 100% for the only parameter 'query', with a description that matches the tool's description. The description adds no new semantic meaning beyond echoing the schema, so baseline 3 applies.

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 lists metro locations with id, city, state, lat/long, and mentions usage with the events tool. Distinguishes from siblings by specifying EDMtrain-specific metro data, though it could explicitly differentiate from other list 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?

Provides guidance on using location id with the events tool and filtering by city/state keyword. Notes geographic scope (North American metros). Lacks explicit when-not-to-use or alternatives, 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?

Beyond the annotations (all false, which is appropriate for a feedback tool), the description discloses important behavioral traits: rate-limited to 5 per identifier per day, doesn't count against tool-call quota, and that feedback is reviewed daily and influences the roadmap. This adds significant context for the agent.

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

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

The description is well-structured with two paragraphs, clear headings for categories, and front-loaded purpose. While it contains multiple pieces of useful information (categories, usage tips, rate limits, free status), it could be slightly more concise by omitting redundant details like 'The team reads digests daily and signal directly affects roadmap,' which is secondary.

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

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

For a feedback submission tool with no output schema, the description covers all necessary context: what to submit, how to structure it, rate limits, cost, and impact. It is complete enough for an agent to understand and use the tool correctly without additional information.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies how to use the message parameter effectively. This extra guidance justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific categories (bug, feature, data_gap, praise) and distinguishes this feedback tool from all sibling tools, which are mainly information retrieval or analysis tools.

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

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

The description provides explicit guidance on when to use each feedback type (bug for wrong/stale data, feature for missing tools, data_gap for missing data, praise for positive experiences) and what to avoid ('don't paste the end-user's prompt'). It also mentions rate limits and that it's free, which aids 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 readOnlyHint, idempotentHint, and destructiveHint. Description adds that data is 'Self-aggregating signal — derived from CF analytics-engine, no PII' and notes caching behavior (5min-1h), providing context 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?

Three sentences, each purposeful: first states result, second lists use cases, third adds privacy and cache info. Front-loaded and no wasted words.

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

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

With one optional parameter, no output schema, and rich annotations, the description fully explains what the tool returns, when to use it, and relevant caveats (caching, no PII). Complete for the tool's complexity.

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

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

Schema coverage is 100% (one parameter with enum). Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which helps choose the right window.

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 'Returns the top tools, top packs, and total call volume over a recent window', which is a specific verb+resource outcome. It also lists three concrete use cases, distinguishing it from the many sibling tools by its unique function.

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

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

Explicitly provides three scenarios when to use the tool (discovering hot data sources, confirming canonical tools, aligning use case). Does not mention alternatives or when not to use, but the use cases are clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial context: algorithms (monotonicity violations, partition checks, Jaccard similarity), partition filter logic, fill_check, and response structure. 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 well-organized and front-loaded with the main purpose and usage. However, it is quite verbose with detailed sections like 'SEMANTIC ANCHOR' and 'PARTITION FILTER', which, while valuable, could be condensed for better conciseness.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill_check). It covers edge cases (placeholders, low similarity) and provides guidance on when to use custom sizing. All necessary behavioral context is present.

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

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

Schema coverage is 100%, but the description adds significant meaning: for event parameter, recommends specific slugs and explains it walks child markets; for topic parameter, explains cross-event scanning and Jaccard similarity. This enriches understanding beyond schema definitions.

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

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

The description clearly states that the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by explicitly mentioning custom sizing via polymarket_fill_risk.

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

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

Explicitly states when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides when-not-to-use guidance (do not trade if realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description provides extensive behavioral context beyond annotations: it details the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), explains the model families and edge calculations (e.g., lognormal barrier from FRED log-returns, partition_overround with per-sport alpha), describes caching (1h at KV level keyed on all knobs), and mentions diagnostics. 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 very long and dense, packing a lot of technical detail into a single paragraph. While every sentence contains useful information, it lacks clear structure (e.g., bullet points, sections) and is not concise. Important information is front-loaded (purpose), but the detailed model explanations could be organized better. There is no wasted text, but the density hurts 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?

Given the tool's complexity (9 parameters, no output schema, nested concepts like partition_overround and Kelly fractions), the description is remarkably complete. It explains the output structure (by_segment with three segments, fed_candidates/fed_note, diagnostics), covers all knobs and their effects, and describes edge calculations. The description compensates for the lack of output schema by providing a detailed schema for the response.

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 9 parameters with 100% description coverage. The tool description adds some context (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity, 'Skips opportunities that are too small' for min_kelly), but most parameter details are already in the schema. The description does not introduce new parameter semantics that are not already present. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is specific about the verb ('scan', 'return'), the resource ('top Polymarket markets'), and the scope ('opportunities where Pipeworx data disagrees'). The sibling tools include 'polymarket_arbitrage' and 'polymarket_edge_tracker', and this description effectively distinguishes itself by focusing on disagreement with Pipeworx data.

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

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

The description provides a clear use case: 'what should I bet on today' and states that agents discover opportunities without paging. It explains the tradeable-edge knobs and how they filter opportunities. However, it does not explicitly state when not to use this tool or compare to alternatives like 'polymarket_arbitrage' or 'bet_research'. The implicit guidance is strong but not fully explicit.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral details: snapshots are written on cache-misses (so gaps exist), decay is computed from daily closes (not intraday), and the response includes trend and decay rate calculations.

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

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

The description is long but well-structured, with clear sections for args, response, and limits. It front-loads the core purpose. While efficient, it could be slightly more concise, but the information density justifies the length.

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

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

Despite no output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) and their semantics. It covers assumptions, limits, and edge cases like gaps in snapshots, making it complete for agent invocation.

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

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

The input schema provides full descriptions for both parameters (days, window), so baseline is 3. The description adds minimal extra meaning, such as 'window family' and the '1wk' default, but does not significantly elaborate 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 provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed. It distinguishes itself from sibling tools like polymarket_edges by focusing on telemetry from daily snapshots.

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

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

The description explains when to use the tool (to differentiate fresh edges from old ones) and mentions limits like the 60-day snapshot TTL. However, it does not explicitly list alternatives or when not to use it, though the context implies its specialized role.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so description's main role is to add behavioral context. It does so by describing internal operations: 'walks the ladder', returns specific fields like top_of_book, vwap_fill_price, slippage_pp, etc. It also explains basket mode behavior and risks like forced directional risk. Slightly verbose but adds value.

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

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

Well-structured with sections for single-market and basket modes. Front-loaded with purpose and requirement. However, some repetition of return fields between modes and slightly verbose explanations reduce conciseness. Each sentence earns its place but could be trimmed.

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 missing output schema, the description lists all return fields for both modes, explains usage context, and warns about risks. Given the complexity (two modes, 4 parameters, no output schema), the description is comprehensive and leaves no major gaps for an agent to understand 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 description coverage is 100%, but the description adds meaningful context: explains required one of market/event, clarifies default side and size behavior, and mentions clamping for size. It also explains how side is auto-detected in basket mode. Adds value beyond schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. The verb 'check' and resource 'edge against order-book depth' are specific. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a fill-risk validation 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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains requirements ('REQUIRES one of market or event') and warns about risks of partial basket fills converting arb to directional position. Provides clear context on when-not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds rich behavioral details: compatibility warnings, temporal alignment, skipped cross types, and the note that real spreads are rare. No contradictions.

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

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

Well-structured with bold headings for modes and safety fields, but somewhat verbose. The final sentence repeats a warning already given, slightly reducing conciseness. Still, each 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?

Despite no output schema, description fully explains response fields (leg prices, spreads, safety fields) and covers input modes, edge cases, and temporal alignment. Comprehensive for a specialized cross-venue analysis 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 has 100% coverage with descriptions and examples. Description adds meaning by explaining the two modes, auto-fetching behavior, and overriding logic. Response fields are also described, compensating for lack of output 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 computes cross-venue spread between Kalshi and Polymarket, with two modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on the cross-venue aspect.

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 describes two usage modes and warns that most macro shortcuts currently yield compatibility warnings, guiding agents not to assume tradeable spreads. Provides clear when-to-use and when-not-to-use information.

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

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

Annotations already cover readOnly, idempotent, non-destructive. The description adds value by explaining the scoping mechanism ('Scoped to your identifier') and the lifecycle pairing with remember and forget, which annotations do not capture.

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

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

Two sentences, each carrying weight. First sentence defines the action, second provides usage and pairing. No redundancy or filler; information is 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 optional parameter and no output schema, the description covers purpose, usage, behavior, and parameter semantics thoroughly. All necessary information for correct invocation is present.

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

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

Schema coverage is 100% with a clear description. The description restates the parameter behavior ('Retrieve... or list all keys') but adds 'via remember' and 'saved keys' for context. This is informative but does not significantly surpass the schema's own 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 starts with a specific verb-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes the dual behavior and references sibling tools (remember, forget) for context, making it distinct from other tools.

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

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

The description explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It provides concrete use cases (ticker, address, notes) and notes scoping and pairing with siblings, though it does not explicitly exclude alternative tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses key behaviors: the mark_read flag for managing read state, filtering by type and since, and the limit range. This adds significant context for correct invocation.

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 well-structured sentences, no redundancy. It front-loads the main purpose, then details data, filtering options, state management, and alternative access. Every sentence earns its place.

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

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

Despite no output schema, the description explains the event structure (source, citation_uri, raw payload). All 5 parameters are covered, annotations are provided, and the context of polling and REST alternative is given. Complete for this tool.

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

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

Schema coverage is 100% with inline descriptions for each parameter. The tool description adds value by explaining the effect of mark_read and the purpose of unread_only, going beyond the schema's basic 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 action (pull fired events) and the resource (subscription feed). It specifies the returned data (source, citation_uri, raw payload) and distinguishes itself from siblings by focusing on 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?

The description advises on polling suitability and mentions an alternative REST endpoint. It implies use for programmatic access, but does not explicitly differentiate from similar tools like 'events' or provide clear 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 readOnlyHint, idempotentHint, etc. The description adds significant behavioral detail: it reveals data sources (SEC EDGAR, GDELT→GNews, USPTO), fallback behavior, and soft-fail note for patents. It also describes the return format (changes[] grouped by source, total_changes, citation URIs), which is valuable beyond annotations.

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

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

The description is a single, somewhat dense paragraph but efficiently packs example queries, source details, parameter guidance, and fallback behavior. It is front-loaded with usage examples, making it scannable. Could benefit from bullet points for clarity, but the content earns its place.

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

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

Given the tool's complexity (multi-source, fallback, no output schema), the description is remarkably complete. It explains every source, the fallback chain, parameter details, and return structure. No output schema means the description must cover return shape, which it does.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining relative shorthand for 'since' (e.g., '7d', '3m') and suggesting '30d' for typical monitoring. It clarifies 'value' can be ticker or CIK. This enrichment justifies a 4.

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

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

The description starts with concrete example queries ('What's new with X', 'latest on Y') and explicitly states the tool provides a change feed for a company from SEC, news, and patents in a recent window. It clearly differentiates from sibling 'entity_profile' by noting when to use each.

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

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

The description provides explicit guidance: 'Use entity_profile instead when you want the static profile', indicating when not to use this tool. It explains the fan-out behavior and fallback logic, giving clear context for appropriate usage.

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

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

The description adds context beyond annotations: key-value pair scoped by identifier, memory persistence differences between authenticated (persistent) and anonymous (24 hours). Annotations provide idempotentHint=true and destructiveHint=false, which are consistent. No contradiction.

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

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

The description is concise and well-structured. It front-loads the core purpose, then provides usage guidance, behavioral details, and sibling references. Every sentence is meaningful with no waste.

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

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

The description fully covers what the tool does, when to use it, how it behaves, and how it relates to sibling tools. Despite no output schema, the description is self-contained and sufficient for an agent to understand the tool.

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

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

Schema coverage is 100% with both parameters described. The description adds examples of key naming conventions and values, which adds some meaning beyond the schema. The baseline is 3 due to high coverage, but the examples earn a 4.

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

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

The description clearly states the tool's purpose: saving data for later reuse. It provides specific examples (resolved ticker, target address, user preference) which makes the intent very clear. It also distinguishes itself from sibling tools by mentioning recall and forget.

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

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

Explicitly tells the agent when to use this tool: when discovering something worth carrying forward. It also provides alternatives: recall for retrieval and forget for deletion. This makes the usage boundaries 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?

The description adds significant behavioral details beyond the annotations: it explains the cascading internal lookup (replacing 2-3 manual calls), auto-disambiguation for company names, and specifies exact output fields (ticker+CIK, RxCUI+ingredient) plus citation URIs. Annotations (readOnlyHint, idempotentHint) are consistent and enhanced.

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

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

The description is well-structured, starting with example queries and a clear usage directive before detailing supported types. It is somewhat long but every sentence adds value. Minor inefficiency: the list of examples could be slightly trimmed, but overall it is effective.

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

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

Given no output schema, the description compensates thoroughly by listing return values for each type. It also explains the resolution process (cascading lookups) and provides citation info. The context about replacing manual lookups aids understanding. The tool's role among siblings is clear.

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 provides rich meaning beyond: it explains accepted formats for 'value' (ticker, CIK, name for company; brand/generic for drug) and explicitly details what each type returns, including additional fields like citation URIs. This fully compensates for the lack of an output schema.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It uses specific verbs like 'resolve' and provides concrete examples (ticker, CIK, RxCUI). It also distinguishes itself from sibling tools by positioning it as the first tool to use when needing an ID.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives clear usage context. It covers two entity types and their input formats. However, it does not explicitly state when NOT to use the tool or mention direct alternatives among sibling tools, though the context is strong enough for an agent to infer.

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 safety (readOnly, idempotent, not destructive). The description adds value by revealing it internally probes with ai_visibility_check and describes the output structure (ranked list with score, confidence, signal density). 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 four sentences, front-loaded with the main action, then explains internal process, gives a use case, and describes output. Every sentence earns its place with zero fluff.

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

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

The description covers input (entities, context, models implied), internal operation (probes ai_visibility_check), and output (ranked list with per-entity score, confidence, signal density). It lacks explicit mention of the apiKey requirement for Anthropic models, but the schema covers that. Overall sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that the first entity in the 'entities' array is treated as the subject and the rest as competitors, and that 'context' disambiguates common names. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility side-by-side across multiple entities, uses ai_visibility_check internally, and outputs a ranked list with specific fields. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (other comparison types).

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

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

The description provides a clear use case example ('competitive AI-marketing audits: does Claude know about us as well as our competitors?') and implies it's for multi-entity comparison. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it fans out across two services, returns a structured summary block (with specific fields), per-advisory detail, links, alternative versions, and explains partial failure behavior when bundlephobia times out.

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 but comprehensive, front-loaded with the main purpose and then expanding on details. Every sentence adds value, and there is no repetition or fluff.

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

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

Despite no output schema, the description fully explains what is returned (summary fields, advisories, links, alternatives), ecosystem limits, and graceful degradation. It is complete for a tool of this complexity and 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 covers 100% of parameters with descriptions. The description adds value by specifying scoped packages and defaulting to latest version, but the schema already provides essential meaning, so a 4 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, aggregating data from deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake support). It distinguishes from siblings by targeting package evaluation specifically.

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 cases: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also clarifies limitations (NPM only in v1, other ecosystems under deps.dev:version) and handles partial failures gracefully with timing notes on bundlephobia.

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 significant behavioral context beyond annotations: details about BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation and flagging, and output structure (character offsets and similarity scores). No contradiction with annotations (all positive hints).

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

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

A single paragraph that is front-loaded with the core action and covers purpose, use case, alternative, technical details, and limits. Every sentence is informative 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?

Despite no output schema, the description sufficiently explains return values (top-N passages with character offsets and similarity scores), algorithm, limits, and integration with a sibling tool. No gaps in understanding.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by providing concrete examples for text and query, explaining limit defaults (5), and describing the output format (passages with offsets and scores), thus enhancing understanding.

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

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

The description clearly states it performs semantic search inside a fetched record with specific verb 'search inside' and resource 'passages'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the use case when a record is too big to fit in the prompt.

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 the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. Provides clear context for usage but does not explicitly list 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?

The description discloses many behavioral traits: required account type, persistence, delivery channels, limitations (SMS cap, webhook auto-disable). It adds context beyond annotations (e.g., openWorldHint is not elaborated, but idempotentHint may conflict with the creation semantics, though description doesn't directly contradict it).

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 well-organized, with separate details for types and delivery channels. It is slightly long but every sentence provides necessary information. Could be more concise with bullet points.

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

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

Given the complexity of the tool (multiple subscription types, delivery options, constraints), the description is comprehensive. It explains return value, requirements, and edge cases, making it complete for agent invocation even without an output schema.

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 fully described. The description adds valuable examples and constraints (e.g., verified phone for SMS, webhook restrictions) that go beyond the schema, aiding correct usage.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides context about requirements (Pipeworx OAuth account) and supported types, but does not explicitly tell when to use this tool versus alternatives such as 'recent_alerts' or 'events'. Usage is implied but not clearly contrasted.

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 that it returns examples from a live catalog, which is behavioral context. No contradictions.

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

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

The description is fairly long but well-structured with front-loaded purpose. Uses slashes to list synonymous phrasings. Every sentence adds value, though 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?

No output schema, but description fully explains return format: category-bucketed examples with tool+argument shapes. Covers parameter behavior and provides sufficient context for an agent to decide when to use this tool.

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

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

Schema covers 100% of the single parameter. Description adds practical usage advice: call with no arguments for full spread or pass topic to focus, with examples like 'finance', 'pharma'. This enriches meaning beyond the schema's 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 it is the onboarding entry point, returning category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by saying 'Use this FIRST'.

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

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

Explicitly says when to use: 'when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also gives alternative use with or without the `topic` parameter.

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

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

Discloses that the row is deactivated not deleted, preserving historical events—beyond annotations. No contradiction with readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true.

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

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

Two sentences, front-loaded with key action, no redundant words. 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 single parameter, no output schema, and annotations, the description is fully complete—covers purpose, ownership, behavioral nuance, and state change impact.

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

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

Schema coverage is 100% with parameter 'id' fully described as 'Subscription id (uuid) returned by subscribe'. Description adds no extra meaning beyond schema, earning 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?

Starts with 'Cancel a subscription by id', clearly specifying verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions by describing ownership enforcement and deactivation behavior.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), giving clear context for when the tool is applicable. Lacks explicit mention of when not to use or alternatives, but clarity is high.

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. The description adds significant behavioral detail: the two verification pathways, exact percent-delta math for financial claims, fallback to grounded pipeline, and verdict types. No contradiction with annotations.

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

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

The description is moderately long but well-structured with trigger phrases upfront and then detailed explanations. Every sentence adds value, though some could be slightly more concise without losing 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 adequately explains return values (verdict, actual value with citation, reasoning). It covers the complexity of the tool (compound operation, two pathways) and provides sufficient context for an AI agent to understand its capabilities.

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

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

Schema coverage is 100% with clear descriptions. The description adds extra meaning: tolerance_pct overrides implied tolerance and provides usage guidance (e.g., set 1–2 for hallucination detection). This goes 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 uses specific verbs and resources ('natural-language claim verification against authoritative sources') and distinguishes itself by replacing 4–6 sequential calls, which sets it apart from sibling tools that may not offer this consolidated 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details two pathways (SEC EDGAR vs. grounded pipeline) for different claim types, giving clear context. However, no explicit 'when not to use' alternative is provided.

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