Arcgis Richmond

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

The description discloses that the default model is Workers AI Llama-3.3-70b (free) and that passing _apiKey enables Anthropic at the user's expense. It notes the return structure (per-model score, confidence, signals, raw_response + combined view). All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description's read-only, non-destructive nature. No contradictions.

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

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

The description is three sentences, each earning its place: first sentence states core function and output, second details model options and cost, third lists use cases. No wasted words, front-loaded with primary action.

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 tool's purpose, input details, model options, cost implications, and output structure. It lists realistic use cases. No output schema exists, but the description describes the return shape sufficiently. Minor gap: it doesn't mention that responses may vary by model or that confidence scores indicate reliability, but overall comprehensive for a probe tool.

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

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

Schema coverage is 100% so parameters are documented. The description adds valuable context: it explains the default model behavior tied to the 'models' parameter, clarifies that `_apiKey` is only needed for Anthropic and passes straight through, and gives an example for 'context'. 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 the tool probes LLMs for business/brand awareness and outputs a visibility score per model (0-100). The verb 'probe' and resource 'LLMs' are specific and unambiguous. It highlights the main use case: AI-marketing audits, pre-launch checks, competitive monitoring, which distinguishes it from sibling tools like `deep_research` or `scan_competitor_ai_presence`.

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

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

The description explains when to use the tool (audits, pre-launch, monitoring) and provides model selection guidance: default is free, Anthropic requires a provided key. It does not explicitly state when not to use it or name alternatives, but the sibling tool list implies other research tools exist. This is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it routes to 4,552 tools across 1160 sources, returns structured answers with pipeworx:// citation URIs, and works on every tier with one fast call. No contradictions with annotations.

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

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

The description is relatively long but well-structured, with clear sections for usage guidance, examples, and differentiation. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the tool's complexity (many siblings, many sources), the description is comprehensive, covering purpose, usage, behavioral traits, and return value (structured answer with citations). No output schema needed as description suffices.

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

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

Schema coverage is 100% with descriptions for all parameters (including aliases). The description does not add extra semantic meaning beyond what the schema provides, but the examples in the input schema help. 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 as a router for factual questions to authoritative structured data, with specific examples and a clear verb-resource pairing. It distinguishes itself from web search and siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly states when to prefer this tool over web search, provides example query types, and explains when to use alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). Includes concrete examples of questions.

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. Description adds that it extracts answer only from tool result, lists refusal reasons, and mentions extra LLM call, providing comprehensive behavioral insight.

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

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

The description is front-loaded with key purpose and usage, but could be slightly shorter. Still, 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?

Despite no output schema, description fully documents return format (answer, evidence, confidence, source, refusal_reason) and possible refusal reasons, making it complete for agent invocation.

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

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

Schema covers all parameters with 100% description coverage. Description adds that the question is in natural language and accepts aliases, which is marginal 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 states it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by noting the extra LLM call and different use case (casual vs. high-stakes).

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 specifies when to use (high-stakes reads, financial/legal/medical) and when to prefer ask_pipeworx (casual lookups), including cost trade-off.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description extensively details behavioral traits: fan-out logic, response shapes, safety mechanisms (low-confidence resolution, closed market handling, wide-spread warnings), resolution-rule risk, and fallback behavior for news fields. It fully discloses the tool's internal behavior and edge cases.

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

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

The description is comprehensive but very long (over 800 words). It is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), but could be more concise. The detail is valuable, but brevity is sacrificed.

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, lack of output schema, and rich annotations, the description is exceptionally complete. It covers all necessary aspects: input handling, response shapes, safety checks, error conditions, and resolution rules. No critical gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter values with concrete examples (slug, URL, question text), defining depth options (quick vs thorough), and clarifying the include_raw flag's effect. This enriches the schema descriptions.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to data packs, and returning an evidence packet with comparison. It distinguishes itself from siblings like polymarket_edge_tracker and polymarket_arbitrage by offering a comprehensive research pipeline.

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 use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear context. However, it does not explicitly state when not to use this tool versus alternatives among the sibling tools.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive traits. The description adds substantial behavioral context: mentions pulling latest 10-K data from SEC EDGAR/XBRL for companies, handling off-calendar fiscal years, sorting by primary metric, and returning paired data with citation URIs. No contradiction with annotations.

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

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

The description is fairly long but every sentence serves a purpose: trigger examples, core function, preference directive, type details, data sources, sorting, return format, and efficiency claim. It could be slightly tighter, but it is well-structured with front-loaded key information.

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

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

Given the tool's complexity (two entity types, multiple metrics) and the absence of an output schema, the description covers essential aspects: what data is retrieved, sorting behavior, and return type (paired data + citation URIs). It does not cover edge cases or error handling, but is adequate for an AI agent to use the tool effectively.

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

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

Schema coverage is 100%, but the description enriches both parameters significantly. For 'type', it explains what data each entity type pulls (company: financials; drug: adverse events, trials). For 'values', it clarifies input formats (tickers/CIKs for companies, names for drugs) and provides examples. This exceeds the basic schema descriptions.

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

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

The description opens with explicit trigger phrases ('Compare X and Y', 'X vs Y', etc.) and clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sibling tools by noting it replaces 8–15 sequential lookups, making its 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 provides explicit when-to-use examples and an imperative directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates between company and drug types, explaining the data sources and metrics, which guides the AI agent on appropriate invocation.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: expected latency (15-60s), output format (findings packet with verbatim evidence, confidence, gaps[]), and the guarantee that it never invents information. 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?

Despite length, every sentence serves a purpose. Front-loaded with critical prerequisite (account), then purpose, then alternatives, then examples. No filler. The structure flows logically from constraints to behavior to output. For a complex tool, this conciseness is appropriate.

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 (many siblings, no output schema, 1160 data sources, 4,552 tools), the description covers account tiers, alternatives, input expectations, output format, limitations (breaking news), and timing. No output schema exists, but the description compensates by detailing the return packet structure. 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 coverage is 100%, but description adds meaning beyond the enum labels: explains depth values (quick=3, standard=5, thorough=8) and ties 'thorough' to paid plans. For question, clarifies that broad/multi-part queries are intended and decomposition is automatic. This eliminates ambiguity about parameter usage.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and distinguishes it from open-web search. It provides concrete examples of good use cases like 'compare X and Y's regulatory + financial exposure' and contrasts with siblings (ask_pipeworx). The verb 'research' paired with the resource 'structured data sources' is specific and unambiguous.

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

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

Explicit guidance on when to use (broad/multi-part questions over structured data) and when not (breaking/colloquial current news). Names the alternative ask_pipeworx for single lookups and live news. Also notes account prerequisite and paid plan requirement for 'thorough' depth. No ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states 'each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

Approximately 5 sentences, front-loaded with the key verb and resource, then covers scope, return format, and usage guidance. Every sentence adds value without redundancy.

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

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

With no output schema, the description fully explains the return: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' Also addresses the 'when' and 'why' of this tool, making it complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description explains that the 'query' parameter accepts natural language descriptions, lists aliases (task, q, search, description), and provides examples that clarify usage beyond the schema's brief descriptions.

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

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

The description uses a specific verb 'Find' and resource 'tools' with detailed scope: browsing/searching over a list of data domains (SEC filings, FDA, etc.). It distinguishes from siblings by being a meta-tool for discovering other tools, as indicated by 'Call this FIRST...' and the return format.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides example queries ('look up FDA drug approvals') and lists domains, giving clear context for when to use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant behavioral details: return fields (CIK, filings, fundamentals, patents with sunset note, news, LEI), soft-fail for USPTO, and parallelism. No contradictions.

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

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

Well-structured with front-loaded examples and bullet-like lists. Slightly verbose with specific patent sunset date, but informative. Concise enough 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?

Covers input constraints, output details, edge cases (patent fallback, name unsupported), and references sibling tool. Without output schema, description fully explains return values.

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

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

Schema coverage is 100% but description adds meaningful context: type only 'company', values ticker or zero-padded CIK, and explicitly notes names are not supported. This goes beyond schema descriptions.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies, with example queries and explicit preference over chaining individual lookups. It distinguishes from siblings by recommending this tool for holistic views.

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 (holistic view, over chaining) and when not (names not supported, recommending resolve_entity first). Provides clear context for selection.

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

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

Annotations already indicate the tool is destructive and idempotent. Description confirms deletion but adds little beyond the annotation flags. No details on error handling or return values.

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 the action. Every word earns its place. Very 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 simple tool (one param, no output schema), the description fully covers purpose, usage, and pairing. No gaps.

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

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

The single parameter 'key' is well-documented in the schema (100% coverage). Description only repeats 'by key' without adding new meaning.

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

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

The description clearly states the tool deletes a memory by key. It mentions pairing with remember and recall, distinguishing it from retrieval and storage. However, it does not explicitly contrast with siblings beyond that.

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

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

Provides specific when-to-use scenarios: stale context, task completion, clearing sensitive data. Does not specify when not to use or alternatives, but pairing guidance is helpful.

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 is read-only, idempotent, and not destructive. The description adds value by explaining the process: fetches the page, extracts title/description/links, and emits standard markdown format. This goes beyond the annotations to clarify the tool's behavior and output.

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

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

The description is four sentences with no fluff. It front-loads the main purpose, then details the process, then lists use cases. Every sentence adds value and it is appropriately sized for the tool's simplicity.

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 there is no output schema, the description fully explains the output as a single text blob ready to drop at site-root/llms.txt. It covers the input parameters, the process, the output format, and three use cases. This is complete for a tool with 2 parameters and no output schema.

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

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

Schema coverage is 100%, but the description adds meaning by mentioning the URL as the site to summarize and specifying the default and max for max_links (default 25, max 50), which is not in the schema description. It also implies the URL parameter's role in fetching the page.

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

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

The description clearly states the tool generates a production-ready llms.txt file for AI crawlers. It uses a specific verb ('generate') and resource ('llms.txt'), and the context of indexing by AI crawlers distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, or auditing competitor. This provides clear context for when to use the tool. However, it does not explicitly say when not to use it or mention alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying the exact information returned (fields, geometry type, record count, capabilities), which is not covered by annotations. No contradictions.

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

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

The description is a single concise sentence that front-loads the action and outcome. Every word is informative and there is no wasted 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 simplicity of the tool (one parameter, no output schema), the description fully explains the tool's purpose and the content it returns. No additional context is needed.

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

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

The input schema already describes the 'url' parameter with an example. The tool description reiterates 'by url' but does not provide additional semantics beyond what the schema offers. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get') and the resource ('ArcGIS Feature/Map Service layer's schema'), listing specific return values (fields, geometry type, record count, capabilities). This distinguishes it from siblings like 'query_layer' which likely retrieves data rather than schema.

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

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

The description mentions 'by url' as the input requirement, implying the tool is used when you have a layer URL and need its schema. It does not explicitly state when not to use or compare to alternatives, but the context of sibling tools (e.g., 'query_layer') provides implicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details like returning specific fields and defaulting to active subscriptions, complementing annotations without contradiction.

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

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

Two sentences: first states purpose and outputs, second gives usage guidance. Front-loaded, no extraneous information.

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

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

Despite no output schema, the description lists all relevant fields. The tool is simple with one optional parameter, and the description covers enough for an agent to use it effectively.

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

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

Schema has 100% description coverage for the one parameter. Description adds value by listing the fields returned, which aids understanding beyond the schema.

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

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

Description starts with 'List the caller's active subscriptions', explicitly stating the verb and resource, and lists the return fields. It clearly distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it doesn't explicitly state when not to use it.

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

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

The description discloses rate limits (5 per identifier per day), that it's free and doesn't count against tool-call quota, and how feedback is processed (digests, roadmap). Annotations do not contradict; they add safety cues (not destructive, not idempotent).

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

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

The description is concise (4 sentences) with front-loaded purpose. Every sentence adds necessary information without redundancy.

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

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

The description covers usage context, rate limits, and expected content. It does not explain return values (no output schema), but for a feedback tool, this is sufficient. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds value by explaining enum values (e.g., bug, feature) and giving practical guidance on message content. This goes beyond the schema's base descriptions.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It uses specific verbs and resources, distinguishing it from sibling tools like ask_pipeworx.

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

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

The description explicitly lists when to use each feedback type and advises against pasting end-user prompts. It mentions rate limits but does not directly contrast with alternatives like ask_pipeworx, though the context implies distinction.

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 value beyond annotations: mentions data source (CF analytics-engine), no PII, (pack, tool, count) data, and caching behavior (5min-1h). Annotations already declare read-only and idempotent; 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?

Five efficient sentences with no redundancy. Front-loaded with core function, then use cases and 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, use cases, data source, privacy, caching. It is fully self-contained and meets all agent needs.

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 defines window parameter with enum and description. Description adds 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which provides extra semantic guidance. With 100% schema coverage, a 4 is appropriate.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window, which is a specific verb+resource. It distinguishes itself from siblings like 'discover_tools' by focusing on aggregated trending data from other AI agents.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, seeing alignment). While no explicit when-not-to-use is given, the context implies it's for aggregate trends; missing exclusions for specific queries are a minor gap.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false. The description confirms safe, read-only behavior by detailing the analysis and fill check. It discloses conditions for not trading (realizable_edge_pp ≤ 0) and internal filters (semantic anchor, partition filter), adding transparency 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 relatively long but well-structured with clear sections. It front-loads the purpose and then organizes by parameter. Every sentence provides essential information for a complex tool, though some technical details (e.g., semantic anchor, partition filter) could be simplified without loss of clarity.

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

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

Given the tool's complexity, the description covers all necessary aspects: input parameters with modes, processing logic, return fields (opportunities array, partition_check), and fill check behavior. It references the sibling tool for sizing, making it self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the behavior of each parameter: no args triggers trending scan, event enables single-event mode with specifics, topic enables cross-event mode. It also provides example values and technical details like Jaccard similarity, enhancing the agent's 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 tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings like polymarket_edges and polymarket_edge_tracker by focusing on arbitrage detection, and describes three modes (no args, event, topic) with clear usage guidance.

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 explains when to use each parameter: no args for trending scan, event for single event mode, topic for cross-event scanning. It also recommends 'event' for specific markets and references the sibling tool polymarket_fill_risk for custom sizing, providing clear guidance on when to use alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing caching (1h KV), model families, response structure with diagnostics like 'filter_skips' and 'funnel counters', and caveats like Fed data limitations, providing comprehensive behavioral insight.

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

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

The description is long but well-structured with clear sections for model families and knobs. Every sentence adds value given the complexity. Slight wordiness in some explanatory parts could be tightened, but overall it is appropriately sized for the tool's sophistication.

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 9 parameters, no output schema, and nested response structure, the description thoroughly covers the tool's behavior, including response top-level fields, diagnostics, caching, and filtering effects. It compensates well for missing output schema by describing the output structure in detail.

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 substantial meaning for each parameter, e.g., explaining slippage_pp in context of Polymarket's zero fees and bid/ask depth, min_liquidity impact on book walking, and min_partition_leg_kelly's role in filtering partitions. This goes beyond the schema definitions.

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

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

The description clearly states that the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like 'polymarket_arbitrage' by detailing its comprehensive multi-model approach and response segments.

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 for discovering betting opportunities and mentions adjustable knobs, but does not explicitly state when not to use this tool or provide direct comparison to sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker' for alternative scenarios.

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

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

Description adds significant behavioral context beyond annotations: 60-day snapshot TTL, snapshots written on cache miss (gaps), response structure with tracked, expired, and snapshot_dates fields, and decay computation from daily closes. Annotations already indicate read-only, idempotent, and non-destructive, and description does not contradict.

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

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

Description is front-loaded with purpose and example, then details response fields and limitations. It is somewhat lengthy but each sentence adds value; could be slightly more concise without losing information.

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

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

Given the tool complexity and no output schema, description fully explains return values (tracked, expired, snapshot_dates) and limitations (TTL, snapshot gaps). It provides sufficient context for an agent to understand what the tool returns and its 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?

Input schema covers 100% of parameters with descriptions. The tool description reiterates defaults and clamps (days: default 14, max 30; window: default '1wk') but does not add substantial new meaning beyond what 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 tool provides 'edge persistence and decay telemetry' from daily snapshots, using specific verbs and resources. It differentiates from sibling tool polymarket_edges by focusing on historical persistence and decay rather than current edges.

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

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

The description gives a concrete use case ('how long has this edge existed and is it shrinking?') and contrasts old vs new wide edges, implying when to use. However, it does not explicitly state when not to use or name specific alternatives beyond the 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?

Description adds substantial behavioral context beyond annotations: it explains that the tool walks the ladder, returns top_of_book, vwap_fill_price, slippage, shares_filled, verdict, and per-leg fill details. It also warns about thin legs and forced directional risk. Annotations already indicate readOnlyHint=true, but description elaborates on internal logic and risks.

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 with uppercase headers for each mode, front-loaded with purpose, then explains parameters, return values, and usage guidelines. Every sentence is informative and there is no wasted text. Length is appropriate for the tool's complexity.

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

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

Despite no output schema, the description comprehensively lists all return fields for both modes (single-market: top_of_book, vwap_fill_price, etc.; basket: theoretical_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, etc.). It also details parameter defaults and constraints (size_usd clamp 10–1,000,000). Covers all necessary context for agent to 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%, but description adds significant meaning: explains that exactly one of `market` or `event` is required, describes default side behavior for basket mode (auto-detect based on partition sum), and clarifies that `size_usd` is interpreted differently for single-market vs basket (settlement notional). This goes beyond the schema descriptions.

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

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

Description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it (before acting on their signals).

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.' Provides clear context for both modes.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds extensive behavioral details: temporal alignment logic, compatibility warning conditions, skipped cross-type/subtype counters, and the rarity of tradable spreads. No contradiction with annotations.

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

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

The description is well-structured with a clear front-loaded purpose followed by modes, response, and safety fields. It is slightly lengthy but each sentence adds necessary context. Could be more concise but remains effective.

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

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

Given the complexity (3 parameters, no output schema), the description is comprehensive. It explains the response structure (leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and covers edge cases. Fully compensates for the missing output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the interaction between topic and explicit parameters, and the override behavior. It does not repeat schema details but enriches the context.

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

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

The description clearly states the tool's purpose as computing the cross-venue spread between Polymarket and Kalshi. It details two modes (topic shortcuts and explicit tickers) and distinguishes it from sibling tools like polymarket_arbitrage by its dual-venue focus.

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 clear context on when to use the tool (to find cross-venue spreads) and provides warnings about the limitations of pre-mapped topics and compatibility issues. It lacks explicit comparisons to alternatives but still offers strong guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns attribute rows and geometry but does not disclose additional behavioral traits like rate limits or performance. With strong annotations, the description adds moderate context.

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

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

Two sentences with front-loaded purpose and parameter details. Every sentence adds value with no waste.

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

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

Given no output schema, the description gives a high-level return format. It covers key aspects of usage (sample, pagination) and is sufficient for an agent to 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%, but the description adds meaning by explaining SQL-like syntax for `where`, comma-separated `out_fields`, examples for `order_by`, and pagination via `limit`/`offset`. This enriches the schema.

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

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

The description clearly states that the tool queries an ArcGIS Feature Service/Map Service layer by URL, with SQL-like parameters. It specifies the resource and distinguishes from siblings like search_datasets (which finds datasets) and layer_info (metadata).

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

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

Provides explicit usage examples (e.g., 'Use where="1=1" + out_fields="*" to sample') and indicates that the URL comes from search_datasets. However, it does not explicitly state when to use alternatives or when not to use this tool.

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

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

Consistent with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds useful context: scoping to identifier and pairing with other tools. 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 concise sentences with no redundancy. First sentence states primary action, second gives use case, third provides scope and related tools. Well structured and front-loaded.

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

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

For a simple retrieval tool with one optional parameter, the description covers purpose, usage, related operations, and scope. No missing critical details given the simplicity and annotations.

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

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

Only parameter 'key' is well described in the schema (100% coverage). The description adds functional nuance: omitting key lists all saved keys, which is valuable guidance beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists keys, with specific verb-resource pairing. It distinguishes from sibling tools 'remember' and 'forget' by explicitly naming them.

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: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Mentions pairing with remember and forget, and scoping to user identifier. No explicit exclusions but strong implied 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 valuable behavioral context about mark_read mutating read state, but this contradicts the readOnlyHint annotation which implies no side effects. The contradiction reduces trust, though the description is otherwise transparent about the effect.

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

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

The description is concise with five short sentences, each adding value: purpose, returned fields, filters, mark_read behavior, and alternative access. No fluff; front-loaded with core purpose.

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

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

Given the parameter count (5) and lack of output schema, the description covers purpose, content, filtering, mark_read, and an alternative. It omits details about the unread_only parameter and limit behavior, but these are documented in schema. Overall, it provides a good high-level understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for mark_read (explaining it causes next call to show only newer events) and mentions an alternative access method (HTTP endpoint). This extra context elevates the score above baseline.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returns recent alerts with specific fields, and distinguishes from siblings like recent_changes by focusing on subscription alerts. The verb 'Pull' and resource 'alerts from subscription feed' are explicit.

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

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

The description provides usage context: filtering by type/since, using mark_read, and notes that polling works fine. It also gives an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus siblings like list_subscriptions or recent_changes.

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

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

Discloses detailed behavioral traits beyond annotations: fans out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and structure of return. No contradiction with annotations (all safety hints are consistent).

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

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

The description is compact and well-structured: query examples, purpose, fan-out details, parameter usage, alternative tool. Every sentence adds value without redundancy.

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

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

Covers all relevant aspects: multiple data sources, fallback behavior, date formats, return structure (grouped changes, total count, URIs), and tool limitations (USPTO sunset). No output schema exists, but the description adequately describes the return.

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

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

Schema coverage is 100%. Description adds meaning by explaining how to use 'since' (ISO date or relative shorthand) and 'value' (ticker or CIK), and provides typical usage advice like 'Use "30d" or "1m" for typical monitoring'.

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

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

The description begins with concrete query examples ('What's new with X', 'latest on Y') and clearly states it is a 'change feed for a company in the last N days/weeks/months'. It explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use the alternative.

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

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

Provides explicit when-to-use examples and direct guidance: 'Use entity_profile instead when you want the static profile'. It also explains the fan-out to multiple sources and the fallback mechanism, giving clear context for invocation.

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

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

Annotations declare idempotentHint=true and destructiveHint=false. Description adds that data is scoped by identifier and provides persistence limits. However, it does not explicitly state overwrite behavior on repeated writes, though idempotency implies safe to repeat.

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

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

Four sentences, front-loaded with purpose, usage conditions, and pairing info. 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?

No output schema, but description adequately covers storage behavior and pairing. A minor gap is lack of return value description, but acceptable for a simple set operation.

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 adds concrete examples for key (e.g., subject_property) and scope, adding 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?

The description clearly states the tool saves data for reuse across conversations or sessions. It uses a specific verb 'save' and resource 'key-value pair', and differentiates from siblings 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 states when to use (discover something worth carrying forward) and pairs with recall/forget as alternatives. Also provides scoping and persistence details: authenticated users get persistent memory, anonymous sessions 24 hours.

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, so the description adds value by noting that each call cascades through several lookup endpoints internally and replaces 2–3 manual lookups. 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 one well-structured paragraph, front-loaded with examples. Each sentence adds value, but it could be more concise by grouping related details. Overall efficient.

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

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

Given the tool's low parameter count and no output schema, the description covers purpose, input formats, output details, and internal behavior. It lacks error handling or not-found cases, but is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100%, baseline 3. The description adds extra meaning by detailing the return fields for each type (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and notes auto-disambiguation for company input. This compensates for missing 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 states the tool resolves names to canonical identifiers, gives concrete examples like ticker, CIK, RxCUI, and explicitly says 'resolves a user-spoken NAME to the canonical/official identifier'. It distinguishes from sibling tools by indicating it should be used first when needing an ID, though it doesn't name alternatives. This is very specific.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context. It lists supported types and what each returns, but does not explicitly state when not to use or mention alternative tools for similar tasks, which would improve the score.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals that it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density per entity. This adds rich behavioral detail without contradicting annotations.

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

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

The description is compact at two sentences, front-loaded with the core purpose, and every phrase adds value. There is 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?

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density per entity). It could slightly improve by specifying the order or structure of the list, but is complete enough for an AI agent to understand the output.

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

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

All parameters are described in the schema (100% coverage), and the description adds extra context: the first entity is treated as the 'subject', models options are clarified ('workers-ai' free default, 'anthropic' requires key), and context disambiguates common names. This significantly enriches parameter meaning.

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

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

The description clearly states the verb 'compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes from the sibling tool 'ai_visibility_check' by noting it uses that tool per entity and ranks results, and from 'compare_entities' by specifying competitive AI-marketing context.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use (comparing multiple entities). However, it does not explicitly state when not to use or name alternative tools for single-entity queries.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds significant context: composite external calls, partial failure handling (bundlephobia timeout), and what happens on failure (sources_failed). No contradictions.

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

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

The description is a single dense paragraph that is front-loaded with the main purpose. Every sentence adds value: usage, limitations, return fields, error handling. No wasted words.

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

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

Despite no output schema, the description enumerates all return fields in detail (summary block, advisories, links, alternatives). It also explains error behavior and time constraints. For a 2-parameter tool, this is impressively complete.

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

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

Schema coverage is 100%. The description adds clarity: scoped packages accepted for 'package', default to latest version for 'version'. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, fanning out to deps.dev and bundlephobia. It specifies the verb 'scan' and the resource 'npm package', and the unique composite nature distinguishes it from sibling tools like 'bet_research' or 'deep_research'.

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

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

The description explicitly says to use when an agent asks about safety, popularity, or size. It also notes ecosystem limitations (NPM only) and mentions that other ecosystems fall under a different tool. While it doesn't provide an exhaustive list of when not to use, the 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 cover safety (readOnly, idempotent, not destructive). Description adds detail on return fields and downstream usage but does not mention rate limits, authentication, or edge cases.

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

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

Two sentences, first sets action and scope, second details return fields and downstream integration. No waste.

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

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

Lists all returned fields and downstream use, but missing details on search behavior (e.g., exact vs fuzzy) and pagination. Adequate for a simple search tool.

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

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

Schema covers 100% of parameters with clear descriptions. The tool description adds no additional semantics 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?

Clearly states verb 'Search' and specific resource ('City of Richmond GIS open geospatial datasets'), includes example dataset types, and distinguishes from sibling tools like query_layer and layer_info that consume the returned URL.

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 workflow hint ('pass that url to query_layer / layer_info') but does not explicitly state when to avoid using this tool or name direct alternatives.

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

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

Annotations already signal read-only, idempotent, non-destructive. The description adds key behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging.

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

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

Four sentences, each adding meaningful information. The main purpose is front-loaded, followed by usage guidance, then technical details. No redundant or vague phrases.

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

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

Given no output schema, the description fully explains the return format (passages with offsets and scores) and internal details (embeddings, windowing, cap). All parameters are described with constraints and examples, making it 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 covers 100% of param descriptions, but the description adds practical constraints ('max ~200K chars' for text, '1-20 default 5' for limit) and example queries for the query parameter, going beyond the schema.

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

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

The description clearly states the verb 'search' and the resource 'inside a fetched record', and distinguishes from siblings like search_datasets by specifying it works on already-fetched text. It gives a concrete use case: 'Use when the record is too big to cram into the prompt.'

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 expands on annotations by detailing delivery channel behaviors (email, SMS with 10/day cap, webhook with HMAC signing and auto-disable after 10 failures). It notes the OAuth requirement. The idempotentHint annotation is not fully addressed (creation might not be idempotent), but no contradiction is present, and the description adds substantial context.

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

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

The description is information-dense but efficiently packaged. The purpose is front-loaded, and every sentence contributes crucial details. It could benefit from bullet points for readability, but given the complexity, it remains clear and structured.

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

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

For a tool with 3 parameters, nested objects, no output schema, and multiple delivery channels, the description is exceptionally complete. It covers supported types with examples, authentication requirements, delivery options with limits and preconditions, and even hints at webhook security. No essential information is missing.

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

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

With schema coverage at 100%, the baseline is 3. The description adds significant value beyond the schema by providing concrete examples for each subscription type and delivery channel settings (e.g., SMS verification, webhook signing). This helps the agent understand parameter usage beyond mere field names.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and specifies the resource and action with precise verbs.

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

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

The description explains when to use the tool (to create subscriptions for specific event types) and states prerequisites (Pipeworx OAuth account). It provides examples for each supported type. While it doesn't explicitly list alternatives when not to use, the context is clear and sufficient for most agents.

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

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

Discloses it is an onboarding entry point, returns live example questions from a catalog, and explains call behavior with/without arguments. Adds context beyond annotations (e.g., exact tool+argument shape, category listing). 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 efficiently structured: starts with trigger phrases, states purpose, explains behavior with/without arguments, and gives usage guidance. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shape) and usage context. Adequately covers input, output, and purpose for an onboarding 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 full description of the optional 'topic' parameter. Description adds extra value by listing possible values (finance, pharma, etc.) and explaining that omitting gives a cross-category spread. With high schema coverage (100%), the baseline is 3; added context raises it to 4.

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

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

The title and description clearly state the tool is for onboarding, returning category-bucketed example questions with exact tool+argument shape. It distinguishes from siblings like 'discover_tools' by focusing on example questions rather than listing 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 advises to use first to learn what Pipeworx can do or how to call meta-tools. Provides when-to-use guidance and mentions optional topic filtering. Does not explicitly exclude other contexts, but the positive guidance 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?

The description adds behavioral context beyond annotations, explaining that the row is deactivated, not deleted, and historical events remain available. This aligns with annotations like destructiveHint=false and readOnlyHint=false, and provides useful operational insight.

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

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

The description is two sentences long, with the primary action in the first sentence and behavioral detail in the second. It is concise, front-loaded, and free of unnecessary 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 tool (1 parameter, no output schema, rich annotations), the description covers ownership and soft-delete behavior, making it complete and sufficient for an AI agent to select and 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?

The schema covers the single parameter 'id' with a description stating it's a UUID from subscribe. The description adds little beyond this, so the baseline score of 3 (due to high schema coverage) 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 'Cancel a subscription by id,' specifying a specific verb ('Cancel') and resource ('subscription'), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions.'

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

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

The description includes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. It does not explicitly mention when not to use it, but the constraint is well-defined.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false, providing a safety profile. The description adds significant context: it returns a verdict (with specific categories), structured form, actual value with citation, and percent delta. It also explains the underlying data sources (SEC EDGAR + XBRL), exceeding what annotations convey.

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 one dense paragraph that front-loads usage examples and then explains functionality and return values. It is concise but could benefit from slight structuring (e.g., bullet points for return types). Overall, it efficiently conveys necessary information.

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

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

Given there is no output schema, the description fully compensates by detailing the return values (verdict types, structured form, actual value, citation, delta). It covers domain, source, and scope completely, making the tool's behavior predictable and actionable.

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

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

The input schema has full description coverage for the single 'claim' parameter. The description adds value by specifying the type of claims it handles (company-financial) and providing examples, which helps the agent construct appropriate inputs.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples of queries and specifies the domain (company-financial claims for public US companies). This distinguishes it from sibling tools like deep_research or compare_entities.

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 whenever the agent needs to check whether something a user said is factually correct.' It also mentions that it replaces 4-6 sequential calls, indicating efficiency. However, it does not explicitly state when not to use it, though the domain limitation is clear.

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