Arcgis Longview

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

Annotations already cover readOnly, openWorld, idempotent, non-destructive. Description adds: default model cost (free), _apiKey pass-through (no storage), return structure (score, confidence, signals, raw_response, combined view). No contradictions.

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

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

Three sentences, no filler. First sentence packs purpose and scoring. Second explains default and BYO key. Third lists use cases. Each sentence essential.

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, parameters, return structure, use cases. No output schema but describes result fields. Missing error/timeout info but adequate for expected 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 description coverage is 100%, baseline 3. Description enriches by explaining default model, optional models array, _apiKey usage (only with anthropic), and context purpose (disambiguation). 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?

Clear verb (probe, score) and resource (LLMs' knowledge about an entity). Specifies default model and optional Anthropic. Distinguishes from sibling tools like deep_research or entity_profile by focusing on AI visibility scoring.

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

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

States use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains when to use default model vs. adding _apiKey for Anthropic. Could mention alternative tools but provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: returns structured answers with stable citation URIs, routes to many sources, and covers a wide domain. There is no contradiction; the description reinforces the non-destructive, read-only nature while explaining internal routing.

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

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

The description is relatively long (about 150 words) but every sentence adds significant value. It is front-loaded with the key guidance 'PREFER OVER WEB SEARCH' and includes examples. Minor verbosity could be trimmed, but overall it is well-structured and informative.

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

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

Given the tool's complexity (routing to thousands of sources), the description is remarkably complete. It covers when to use, alternatives, return format (structured answer with citation URIs), and provides diverse examples. The absence of an output schema is mitigated by describing the output. The sibling tools list is large and the description helps differentiate.

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

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

Schema description coverage is 100%, and the description adds meaning beyond the schema by listing aliases (q, text, input, query, prompt) and providing concrete examples of questions. This helps agents understand how to phrase inputs and what types of questions are suitable.

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: routing questions to 4,774 verified sources and returning structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, specifying when to use each. The verb 'ask' and resource 'Pipeworx' are specific and unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use criteria (factual questions, real-world entities, domains like SEC filings, FDA data, etc.). It also tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad/multi-part questions), offering clear exclusions.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). Description adds process details (routing, extraction, evidence) and return format with refusal reasons. No contradiction; the extra LLM call cost is noted, adding value beyond annotations.

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

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

The description is thorough but slightly verbose. It front-loads the core purpose, then details behavior and return format. Every sentence contributes, but could be trimmed slightly 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?

Despite no output schema, the description fully explains the return structure, refusal reasons, and underlying process. Covers the complexity of routing among many tools. Sufficient for most use cases.

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

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

Schema coverage is 100% and each parameter has a description. The description doesn't provide additional meaning beyond what the schema already specifies (aliases). Baseline 3 is appropriate; no incremental value.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, specifying it extracts answers using only tool results. It draws a direct distinction from the sibling 'ask_pipeworx' by noting the additional LLM call cost, making the purpose unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with domain examples. Also advises preferring 'ask_pipeworx' for casual lookups, providing clear alternatives.

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

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

The description comprehensively discloses behavior: market resolution, classification, fan-out, response shapes (market, analysis, evidence), low-confidence handling, closed markets, wide spreads, cancellation rules, and safety mechanisms. It adds extensive context beyond the annotations (readOnlyHint, idempotentHint), which already indicate safety.

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

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

The description is a single large paragraph covering many details. It front-loads the core purpose but then diverges into extensive examples, classifiers, fan-out specifics, and response shapes. While comprehensive, it could be more structured and concise.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all essential aspects: usage, input examples, classification system, fan-out logic, response fields, edge cases (low confidence, closed markets, illiquid spreads), and cancellation rules. It is fully self-contained.

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 parameter descriptions in the schema are clear. The description adds value by providing examples for the 'market' parameter (slug, URL, question text) and clarifying the 'depth' parameter with concrete definitions. This exceeds the baseline of 3.

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

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

The description clearly states the verb 'Research' and the resource 'a Polymarket bet by pulling the relevant Pipeworx data'. It distinguishes from siblings like ask_pipeworx, polymarket_arbitrage, and polymarket_edge_tracker by specifying its unique scope and outputs.

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 recommends use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides examples but lacks explicit exclusions (e.g., when not to use). However, the context from siblings implies 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?

Beyond annotations (readOnly, idempotent), the description details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles of fiscal years, sorting by primary metric, and output format with citation URIs. This is comprehensive behavioral disclosure.

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 thorough but slightly verbose (multiple sentences). However, it is well-structured with use-case examples first, then detailed behavior. Every sentence adds value, but it could be tightened by 10-20% 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 explains return values (paired data + citation URIs) and sorting behavior. It covers entity types, data sources, and constraints. Missing explicit mention of error handling or rate limits, but overall complete for a read-only 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%, providing baseline 3. The description adds value by explaining what each 'type' value retrieves, how 'values' arrays are used, and provides examples (tickers, drug names). It also notes range constraints (2-5), going 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 explicitly states the tool does side-by-side comparison of 2-5 entities using specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sequential lookups and lists example queries, making the purpose unmistakable.

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

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

The description clearly advises to prefer this tool over sequential single-pack lookups and explains what use cases it replaces (8-15 sequential lookups). It does not explicitly mention when NOT to use it, such as for single entities, but provides strong usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: account required, depth tiers with facet counts, parallelism, output format (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps), expected 15-60s, and the limitation that breaking news yields empty gaps. 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 long but every sentence adds essential information (purpose, constraints, usage, output, timing). It is front-loaded with the critical account requirement. While verbose, the density of useful details justifies the length; slight reduction could improve conciseness.

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

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

Given no output schema, the description thoroughly explains the return value (findings packet with specific fields) and behavior (gaps for unanswered facets, not open-web search). It accounts for complexity with parallelism, routing, and timing, leaving no critical gaps for an agent to select/invoke correctly.

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

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

Schema coverage is 100% with descriptions. The description enriches both parameters: for 'depth' it explains the meaning beyond enum values (quick=3, standard=5, thorough=8 facets), and for 'question' it clarifies that broad/multi-part is appropriate, adding significant value.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources', with a specific verb and resource. It distinguishes from siblings by contrasting with ask_pipeworx for single lookups and breaking news, making the purpose unambiguous.

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

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

The description explicitly says when to use (broad/multi-part questions over structured data) and when not to (single lookup or breaking/current news, directing to ask_pipeworx). It also notes account requirements and tier limitations, providing comprehensive 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 significant behavioral context beyond the annotations: it explains that the tool returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' The annotations already indicate readOnly and idempotent, and the description does not contradict them.

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 a clear opening sentence stating the core purpose, followed by usage guidance, output format, and a call-to-action. It contains multiple sentences but each adds value. Minor redundancy in listing aliases twice (schema and description) could be streamlined, but overall it is efficient.

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

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

For a discovery tool with 6 parameters and no output schema, the description is remarkably complete. It explains the input (query), the output (top-N tools with schemas and examples), and the strategic context (call first). It addresses the agent's need to navigate a large tool set.

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 baseline is 3, but the description adds substantial value: it provides natural language examples in the schema, explains that 'query' accepts multiple aliases (task, q, description, search), and gives examples of valid queries. This goes beyond the basic schema information.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (discover tools) and the resource (tools available to the agent). The description distinguishes the tool from siblings by noting that it returns full schemas with examples and is meant to be called 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?

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist.' It provides concrete examples of use cases (SEC filings, FDA drugs, etc.) and includes a directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint. Description adds concrete behavioral details: fans out across multiple sources, returns specific fields, soft-fails for patents, makes a single parallel call. 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 somewhat lengthy; however, every sentence adds value and it is well-structured with examples upfront.

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 thoroughly explains what is returned: cik, company_name, recent_filings, fundamentals, patents, news, LEI. Includes constraints like soft-fail for patents and URI format.

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

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

Schema coverage is 100% with descriptions. Description adds context: examples of ticker and CIK, clarifies type enum is limited to 'company', and explicitly says names not supported.

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

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

Description explicitly states: 'full cross-source profile of a US public company in ONE parallel call.' This distinguishes it from specific lookups and clearly defines the tool's purpose.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and states names are not supported, instructing to use resolve_entity first.

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, so description adds no extra behavioral context beyond stating 'Delete'. It does not contradict annotations.

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

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

Extremely concise: two sentences, no wasted words. Front-loaded with the action and resource.

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

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

Given the simple single-parameter destructive tool with annotations covering safety, the description is sufficient. Could mention irreversibility, but annotations already indicate destructive nature.

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

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

Schema coverage is 100%, and the description does not add any meaning to the 'key' parameter beyond what the schema already provides ('Memory key to delete').

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

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

Clear verb 'Delete' and resource 'memory by key'. Mentions companion tools 'remember and recall' for context, but lacks explicit differentiation from other deletion tools if any exist.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Also suggests pairing with remember and recall. Does not specify when not to use, 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?

Description adds significant behavioral context beyond annotations: fetches page, extracts title/description/key links, emits standard markdown. Aligns with annotations (readOnly, idempotent, non-destructive) and does not contradict them.

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 dense sentences covering purpose, mechanism, output format, and use cases. No waste, front-loaded with 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?

Without output schema, description clarifies output as 'single text blob ready to drop at site-root/llms.txt'. Sufficient for simple generation tool, though output format details could be more explicit.

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

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

Schema provides 100% coverage for both parameters (url, max_links). Description adds usage context ('any URL', 'production-ready') but does not significantly extend semantic meaning beyond schema.

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

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

Clearly states the tool generates an llms.txt file for AI crawlers, with specific verb 'Generate' and resource 'llms.txt file from any URL'. Distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than presence scanning.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Lacks explicit when-not-to-use or alternative comparisons, but context is clear enough.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context by detailing the specific schema components returned, which enhances understanding beyond the annotations.

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

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

The description is a single, clear sentence with no wasted words. It is front-loaded with the main action and resource.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: fields, geometry type, total record count, and capabilities. This is sufficient for a simple schema retrieval tool.

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

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

Schema coverage is 100% for the single parameter 'url', which already includes a description and example. The tool description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Get', the resource 'ArcGIS Feature/Map Service layer's schema', and specifies the returned data: fields, geometry type, total record count, and capabilities. It is specific and distinguishes itself from sibling tools like query_layer by focusing on schema retrieval.

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

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

The description implies usage via URL but does not explicitly state when to use this tool versus alternatives such as query_layer. There is no guidance on prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by detailing the return format (fields like 'id, type, params...') and the scope ('caller's active subscriptions'). 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 composed of three concise sentences. The first sentence front-loads the purpose, the second lists return fields, and the third provides usage guidance. No unnecessary words.

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

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

Given the tool's simplicity, the rich schema with one parameter, the absence of an output schema is compensated by the description explicitly listing return fields. The context signals and sibling tools provide additional context. The description is complete for correct invocation and decision-making.

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 single parameter 'include_inactive' already has a description. The tool description does not add extra semantic meaning beyond what the schema provides, earning the baseline score.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'. It also enumerates the returned fields, leaving no ambiguity about what the tool does.

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 this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicitly contrasts with the 'subscribe' and 'unsubscribe' 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?

Description adds behavioral traits beyond annotations: rate limit, free usage, not counted against quota, and that the team reads it daily affecting roadmap. Annotations already indicate non-readonly, non-idempotent, etc., and description is consistent and complementary.

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 paragraph with clear structure: purpose, usage scenarios, constraints. Every sentence adds value. Front-loaded with main action. No wasted words.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description fully covers what an agent needs: types of feedback, optional context, message constraints, and rate limits. Explanations are sufficient for correct invocation.

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

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

Input schema has 100% description coverage (all 3 parameters described). The description adds no new parameter-specific details; it reinforces the type values and context structure. Baseline 3 is appropriate since the schema already provides meaning.

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

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

The description starts with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose. It distinguishes itself from sibling tools like ask_pipeworx (which is for asking questions) by focusing on feedback submission. Title 'Send Pipeworx Feedback' also clarifies the action.

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

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

Explicitly states when to use: for bugs (wrong/stale data), features/data_gaps, and praise. Provides 'Don't paste the end-user's prompt' as a specific instruction. Mentions rate limit (5 per identifier per day) and that it's free and doesn't count against quota, helping the agent decide 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 behavioral details beyond annotations: source (CF analytics-engine), no PII, cache duration (5min-1h), and that it's self-aggregating. This complements the read-only and idempotent hints perfectly. 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: four sentences front-loaded with the core function, followed by bullet-like use cases. Every sentence adds value, no fluff.

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

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

Given that the tool has one optional parameter, no output schema, but rich annotations, the description adequately explains what is returned (top tools, top packs, total call volume) and the source. Minor omission: the format of the output (e.g., ranked list) is not explicitly stated, but overall complete enough.

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

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

The schema covers the single parameter with enum and description, but the description adds value by explaining the effect of different windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This enhances understanding beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, with specific time ranges. The title 'Pipeworx Trending' is descriptive and distinguishes it from sibling tools that focus on actual content or actions.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). It provides clear context for when to use, though it doesn't explicitly state when not to use or mention 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?

The description extensively discloses behavioral traits beyond annotations: it walks child markets, checks date-axis/threshold-axis ordering, computes partition_check with sum of YES prices, applies semantic anchor with Jaccard similarity, partition filter for placeholders, and fill check against CLOB depth. Annotations already indicate read-only, idempotent, and non-destructive, which the description confirms.

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 verbose but every sentence adds value. It could be slightly restructured for clarity, but the front-loaded information about modes and recommended usage makes it effective. Minor room for improvement in paragraph organization.

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 complex tool with two modes, multiple checks (monotonicity, partition, fill), and response details, the description provides comprehensive context. It covers edge cases (placeholder slugs, low similarity), explains response fields, and even includes an alternative tool reference. No output schema is present, but the response structure is well documented.

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

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

Both parameters have schema-level descriptions covering 100% of coverage. The description adds significant semantic value: explaining that event triggers single-event mode with partition_check, and topic triggers cross-event scanning with semantic anchor. It also provides usage recommendations and examples for each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and provides specific examples, making the purpose unmistakable and distinct from sibling tools.

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

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

Explicitly says call with no args for a trending scan, recommends event for specific markets, and topic for cross-event scanning. Provides guidance on when not to trade via fill check. Also mentions an alternative tool (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 already indicate read-only, idempotent, non-destructive behavior. The description adds extensive detail: 1-hour KV-level caching, response structure including diagnostics and Fed candidates, model families, and edge computations. 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 verbose (≈500 words) but well-structured with clear segments and knobs. Every sentence adds value for a complex tool, but it could be more concise without losing essential details. Front-loads purpose effectively.

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), the description covers caching, response segmentation, model internals, tradeable-edge filters, diagnostics for empty segments, and Fed bet handling. It provides all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so every parameter is documented. The description adds significant context beyond the schema, such as explaining min_partition_leg_kelly's role in filtering partitions despite min_kelly's default behavior, and providing realistic defaults for slippage_pp.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly frames it for the 'what should I bet on today' use case. It distinguishes itself by detailing three model segments not found in sibling tools like polymarket_arbitrage.

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

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

The description provides context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs with guidance on setting filters (e.g., 'bump for very thin partitions'). However, it does not explicitly state when to avoid this tool in favor of siblings like polymarket_arbitrage.

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

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

Description adds significant behavioral context beyond annotations: reads from daily snapshots with 60-day TTL, decay from daily closes (not intraday), gaps when no scan happened, and detailed response structure. Consistent with readOnlyHint, openWorldHint, idempotentHint.

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

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

Front-loaded with purpose, then response structure, then limits. Some verbosity in response explanation but necessary for clarity given no output schema. 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 provided, so description fully explains return values: tracked[], expired[], snapshot_dates[] with key fields. Also covers limits (snapshot TTL, decay computation) and data gaps, making it complete for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with descriptions for both 'days' and 'window' parameters. Description restates defaults and limits (e.g., 'default 14, max 30') but adds no new semantic information beyond the schema.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Distinguishes itself from sibling 'polymarket_edges' by focusing on temporal analysis: 'how long has this edge existed and is it shrinking?' Contrasts fresh vs old edges.

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

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

Answers specific question about edge existence and decay, providing context for when to use ('a fresh wide edge and a 3-week-old wide edge are different trades'). Mentions median lifespan as competition clock, but does not explicitly state when not to use or 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 (readOnlyHint, idempotentHint) align with description's check nature. Description adds details: walks the ladder, returns specific fields, explains basket mode forced directional risk. 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?

Long but dense with information. Front-loaded purpose. Every sentence is useful. Could be slightly more structured (e.g., separate sections), but appropriate for complex tool.

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

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

No output schema, but description lists all return fields for both modes. Explains dominant loss mode (partial basket fills → directional risk). Thorough for 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 100%, but description adds significant meaning: explains each parameter's role in both modes, defaults, constraints (clamp 10–1,000,000), and auto-detection for basket side. Goes beyond schema.

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

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

Description clearly states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. Distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', explains why (theoretical overround not capturable, partial basket fills create directional risk). States required parameter conditions.

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

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

Annotations already indicate safe read-only operation; description adds rich behavioral context: explains compatibility_warning, temporal_alignment, skipped_cross_type/subtype counters, and response structure (leg-by-leg prices, top_spreads_pp). 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?

Well-structured with clear sections (purpose, signal concept, modes, response fields, safety fields). Slightly verbose but every sentence adds meaningful information; no fluff.

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

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

Covers important aspects: return fields (prices, spreads), safety warnings, edge cases (incompatible shapes, temporal misalignment). Lacks explicit return format structure but compensates with descriptive text; no output schema needed.

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

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

Schema already covers all parameters with descriptions (100% coverage). Description adds value by listing the 10 topic shortcuts, explaining override behavior, and contextualizing 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 computes cross-venue spread for the same resolving question, explains two modes (topic shortcuts and explicit tickers), and distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explicitly explains when to use each mode, warns that most pre-mapped topics return compatibility_warning and thus not tradeable, and describes conditions where no arbitrage exists.

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

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

Description discloses that the tool returns attribute rows and geometry, adding value beyond annotations which already indicate safe, idempotent read behavior. No contradictions; behavioral details are sufficient.

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

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

Two concise sentences with a helpful tip. No redundant information; every part 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?

With no output schema, description mentions return format (rows and geometry). Covers all parameters adequately. Annotations provide safety context. Complete enough for effective use, though pagination behavior could be elaborated.

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 description enriches understanding by summarizing SQL-like where clause, comma-separated out_fields, and order_by/limit/offset usage. The sampling tip provides practical parameter guidance beyond schema.

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

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

Description clearly states the tool queries an ArcGIS Feature/Map Service layer, specifying the resource type and action. It distinguishes from siblings by noting the url comes from 'search_datasets', a complementary sibling 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?

Provides clear context by mentioning the prerequisite of using 'search_datasets' to obtain the URL and offers a practical tip for sampling data. However, lacks explicit when-not-to-use or alternative tool comparisons.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and pairing with other tools, going 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, front-loaded with purpose, no wasted words. Clearly structured with action, use-case, and pairing hints.

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 annotations covering safety, the description fully explains behavior for both providing a key and omitting it. Complete and 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%. Description reiterates what the schema already says about the 'key' parameter (omit to list all). No additional semantics beyond schema, so baseline score of 3.

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

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

Description clearly states the verb 'Retrieve' and the resource 'value previously saved via remember', and distinguishes from siblings by mentioning 'list all saved keys'. It also specifies scoping by identifier.

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 for looking up stored context to avoid re-derivation, and pairs with remember/forget. Could be improved by stating when not to use, but given the tool's simplicity, it's clear.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already assure safety. The description adds behavioral context: mark_read side effect, return fields, and polling suitability. 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?

Single paragraph with clear sentence sequence: purpose, return fields, filters, side-effect, polling hint. Concise but lacks visual structuring (e.g., bullet points) for rapid scanning.

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

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

Covers parameters, return fields, side effects, and alternative access. Missing details on pagination beyond limit (max 200) and ordering implied by 'most recent' but not explicit. Adequate for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by giving example for type ('sec_8k'), clarifying mark_read's effect on next call, and implying limit defaults. This enhances parameter understanding beyond schema.

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

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

The description clearly states the action ('Pull fired events'), the resource ('subscription feed'), and what the tool returns (source, citation_uri, raw payload). It distinguishes from siblings like list_subscriptions by focusing on alerts with event payloads.

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 filtering (type, since) and side-effect parameter (mark_read). Mentions polling works fine and an alternative REST endpoint. However, does not explicitly state when not to use or compare to sibling tools like recall.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: fans out to multiple sources with fallback logic (GDELT→GNews), soft-fails for USPTO, and describes return structure (changes grouped by source, total_changes count, URIs).

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, but well-structured: starts with usage examples, then explains sources, parameters, return structure, and ends with sibling differentiation. Efficient but could be slightly more streamlined.

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

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

Despite no output schema, the description explains return structure (changes grouped by source, total_changes, citation URIs). It covers fallback logic, soft-fail, and explicitly contrasts with entity_profile. All necessary context for agent invocation.

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

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

Schema already covers all parameters. The description adds context: 'since' explains ISO and relative formats plus typical usage '30d' or '1m', and 'value' mentions ticker or CIK. This enriches understanding beyond the schema.

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

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

The description starts with clear user query examples, then states the tool provides a change feed for a company in a specified time window, fanning out to multiple sources. It explicitly distinguishes from entity_profile, making purpose distinct.

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 examples (e.g., 'what's new with X') and tells when not to use it: 'Use entity_profile instead when you want the static profile...'. This provides clear 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?

Adds significant context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous), and storage duration (24 hours for anonymous). Annotations provide idempotentHint but 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?

Three efficient sentences: purpose, when to use, and scope/persistence. Each sentence delivers distinct 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 2-param tool without output schema, the description covers purpose, usage, scope, persistence, and pairing with siblings. Nothing missing.

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

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

Schema already has 100% coverage with good descriptions. Description adds value by showing example keys and values (subject_property, target_ticker), clarifying usage beyond schema.

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

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

Description clearly states the tool saves data for reuse, gives concrete examples (resolved ticker, user preference), and specifies key-value pairs. It distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward'), pairs with recall/forget, and notes authentication scoping. No exclusions needed.

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

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

Annotations already provide safety hints (readOnly, idempotent, not destructive). The description adds behavioral details: cascading lookups, auto-disambiguation, and citation URIs. No contradiction.

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

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

Single paragraph with clear structure: question patterns, purpose, supported types with details. 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 fully explains return values for both types, including citation URIs. Covers purpose, usage, and behavior completely.

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

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

Schema coverage is 100%, and the description adds examples (AAPL, 0000320193, ozempic) and clarifies auto-disambiguation for company type. 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 the tool resolves user-spoken names to canonical identifiers, with specific examples (ticker, CIK, RxCUI) and supported types (company, drug). It distinguishes itself from sibling tools by noting it replaces 2-3 manual lookups.

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

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

Explicitly instructs to use when you have a name but need an ID, and provides type-specific guidance. Does not explicitly state when not to use, but the context is clear.

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

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

Describes that it internally probes each entity via ai_visibility_check and returns ranked list with score, confidence, signal density. Adds context beyond annotations (ranking, output fields). No contradiction with annotations.

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

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

Two tightly written sentences plus a concrete example. Every sentence adds value; no redundancy or fluff.

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

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

Explains return format (ranked list with score, confidence, signal density) despite no output schema. Covers key aspects; could mention error handling or limits, but acceptable for a read-only 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 provides 100% coverage for parameters; description adds marginal value (e.g., first entity treated as subject). Baseline applicable as description doesn't significantly extend param 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?

Clearly states it compares multiple entities' AI visibility side-by-side, distinguishes from sibling tools like ai_visibility_check (single entity). Use case illustrated via competitive audit scenario.

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 frames usage as competitive AI-marketing audits, comparing your brand vs competitors. Implicitly suggests when not to use (single-entity check) via context, but no explicit exclusions.

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

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

Annotations (readOnlyHint, idempotentHint) are present and description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list. No contradiction.

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

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

Description is well-structured, front-loading core purpose, detailing sources, output fields, and edge cases. Slightly long but 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 explicitly lists return fields (summary block, per-advisory detail, links, recent alternatives). Covers partial failures and timing constraints.

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

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

Schema already describes both parameters (package, version) with 100% coverage. Description adds value by noting scoped packages accepted and version defaults to latest published.

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

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

Description clearly states the tool composites a 'should I add this npm package to my project' check across multiple services (deps.dev, bundlephobia), specifying verb and resource. Distinct from sibling tools like scan_competitor_ai_presence.

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

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

Explicit usage: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also specifies ecosystem limitations: 'NPM ecosystem only in v1' and directs to alternative for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by specifying return fields and downstream use, but does not disclose pagination, rate limits, or other behavior.

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

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

Two efficient sentences, front-loaded with action and scope, 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?

All parameters documented, output described explicitly despite no output schema. Only minor missing details about search behavior (e.g., fuzzy vs exact).

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

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

Schema coverage is 100%; description does not add new parameter details beyond what the schema already provides, 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 the tool searches City of Longview GIS datasets by keyword, lists return fields, and explicitly mentions downstream tools (query_layer, layer_info), distinguishing it from siblings.

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 context for use (searching GIS datasets) and hints at subsequent steps (pass url to query_layer/layer_info), but does not explicitly state when not to use or compare to alternative search 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping windows), similarity metric (cosine), character cap (200K chars), and truncation flagging. No contradiction with annotations.

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

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

The description is a single well-structured paragraph without fluff. It front-loads the purpose, then explains usage, pairs with a sibling, and finally provides technical details. Every sentence adds value.

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

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

Given the complexity of the tool and the absence of an output schema, the description covers all necessary aspects: inputs, outputs (passages with offsets and scores), limitations (200K char cap, truncation), usage context, and integration with a sibling. It also includes technical details about the embeddings model and algorithm.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description further explains the purpose of each parameter (e.g., 'text' is the document, 'query' is natural-language with examples, 'limit' is max passages) and describes the output format (passages with offsets and scores), compensating 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 performs semantic search inside a fetched record. It uses specific verbs like 'search inside' and specifies the resource as 'fetched record/text'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and being used when the record is too large for 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?

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also mentions pairing with a sibling tool. However, it does not exhaustively compare to all siblings or state explicit when-not-to-use conditions.

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 behavioral traits beyond what annotations provide: it explains auth requirements, rate limits (SMS 10/day), webhook auto-disable after 10 failures, and one-time secret retrieval. Annotations already indicate idempotent and non-destructive, and description aligns fully 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 information-dense and well-structured, with clear sections for auth, types, and delivery. It avoids redundancy, but minor formatting improvements (e.g., bullet lists) could enhance readability. Overall, 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?

Given the tool's complexity (3 params, no output schema, multiple types and delivery options), the description is complete. It covers all necessary aspects: auth prerequisite, type-specific params, delivery behavior and constraints, and expected return value. The agent has sufficient information to use the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning with concrete JSON examples for each subscription type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailed behavior for delivery channels (validation, signing, limits). This greatly aids parameter understanding.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), and explicitly mentions the return value ('Returns the new subscription id'). This distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description provides explicit guidance on when to use (requires Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions), details supported subscription types with inline examples, and explains delivery channels with constraints (phone verification, daily caps, webhook HMAC signing). This effectively helps the agent decide when and how to invoke the 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by detailing what the tool returns (category-bucketed example questions with exact tool+argument shapes) and that it draws from a live catalog. This goes beyond the annotations to set accurate expectations.

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

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

The description is a single paragraph that front-loads the natural language queries and then efficiently covers purpose, output, and usage. Every sentence adds value, but it could benefit from slight restructuring for readability. It is concise and informative.

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

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

Given the tool has one optional parameter and no output schema, the description fully sets expectations. It explains when to use it, what it returns (category-bucketed examples with tool+argument shapes), and how to invoke it with or without a topic. This is sufficient for an agent to understand the tool's role and behavior.

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

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

Schema coverage is 100%, so the schema already documents the topic parameter with a list of valid values. The description adds example usage ('e.g. 'finance', 'pharma', 'betting'') and the word 'focus' but does not introduce new information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as the onboarding entry point for agents to discover what Pipeworx can do. It lists natural language triggers and explains that it returns category-bucketed example questions with tool+argument shapes. This differentiates it from siblings by positioning it as the first tool to call when exploring capabilities.

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 instructs to use this tool 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains that calling with no arguments gives a full spread, while passing a topic focuses results. However, it does not explicitly contrast with siblings like discover_tools, so it gets a 4 instead of a 5.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds behavioral context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the non-destructive nature and side effect, going 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?

Three sentences, each conveying essential information: action, ownership rule, and deactivation behavior. No redundant or superfluous text.

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

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

Given the simple parameter schema and no output schema, the description covers purpose, ownership, and side effects. It misses the success response format, but overall it's sufficient for correct tool invocation.

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

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

Schema coverage is 100%, and the parameter 'id' is described in the schema as 'Subscription id (uuid) returned by subscribe.' The description adds only 'Cancel a subscription by id,' which is already implied by the tool name and schema. No additional 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 'Cancel a subscription by id' with specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by describing the cancellation action and ownership enforcement.

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 usage constraint: 'Ownership is enforced — you can only cancel your own subscriptions.' This tells when it's applicable but doesn't explicitly state when not to use it or list alternatives, though the constraint is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, establishing a safe, non-destructive profile. The description adds valuable behavioral context: it uses SEC EDGAR + XBRL, returns structured verdicts and citations, and replaces multiple sequential calls. This goes beyond the annotations without contradicting them.

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

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

The description is a single paragraph that efficiently opens with trigger phrases, states the purpose, and provides usage guidance and return details. It is dense but not bloated, and every sentence contributes value. Minor improvement could be splitting into bullet points for readability.

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

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

The description covers the main functionality, supported claim types, and return format. However, it lacks information about limitations (only public US companies, financial claims), error handling, or what happens when a claim is unsupported. Given no output schema, the description carries the burden of completeness, and these gaps lower the score.

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 schema already documents the 'claim' parameter with examples. The description adds domain-specific context (company-financial claims, SEC EDGAR) and clarifies the scope, which meaningfully enhances understanding beyond the schema.

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

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

The description clearly defines the tool as a natural-language claim verification system against authoritative sources, with specific examples like 'Is it true that…' and 'fact check'. It distinguishes itself from siblings by noting it replaces 4–6 sequential calls, and the verb+resource (validate claim) is precise.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' While it provides a clear usage context, it does not mention when not to use it or explicitly compare to alternatives like other research tools in the sibling list.

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