Arcgis Toledo

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, making the tool's safety clear. The description adds valuable behavioral details: probing multiple LLMs, scoring methodology (0-100), and the pay-as-you-go model for Anthropic. It does not contradict annotations and expands on the expected behavior beyond what annotations provide.

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

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

The description is extremely concise: just two sentences. The first sentence front-loads the action, resource, and output format. The second sentence adds use cases. Every word is functional, no redundancy or filler.

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 appropriately details the return structure (per-model score, confidence, signals, raw_response, plus combined view). It also provides use case context. While it could mention potential errors or rate limits, for a read-only, idempotent tool with 4 well-documented parameters, it is nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor context beyond the schema (e.g., default model, when `_apiKey` is needed), but the schema already adequately describes each parameter. The description does not significantly enhance parameter 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's specific action: probe LLMs for knowledge about an entity and score visibility (0-100). It distinguishes from siblings by focusing on AI visibility scoring with a default free model, a clear use case (AI-marketing audits, pre-launch brand checks, competitive monitoring), and a unique output format. Despite potential overlap with 'scan_competitor_ai_presence', the specificity of the scoring and return structure sets it apart.

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 contexts for use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and guidance on when to use the optional `_apiKey` and `models` parameters. However, it does not explicitly differentiate from siblings or provide when-not-to-use scenarios, which would elevate clarity further.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it routes questions, fills arguments, and returns structured answers with citation URIs. It also notes that it works on every tier and is a single fast call, going beyond annotation basics. No contradiction.

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

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

The description is broadly structured and front-loaded: it opens with the key preference directive, then explains mechanism, provides examples, and closes with alternative tools. It is somewhat long, but every sentence carries distinct information, so the length is justified for a meta-tool with many usage nuances.

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 is highly complete for a tool with no output schema. It covers what it does, when to use it, how to use it (with examples), what to expect in return (structured answer with citation URIs), and how it relates to alternatives. It leaves no significant gaps in the given context.

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

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

The schema has 100% coverage with all six parameters being aliases for 'question', each described as 'Alias for question.' The description significantly adds meaning by explaining what type of natural language question to ask (e.g., 'what is', 'look up', 'find') and providing six concrete examples that illustrate the expected input format.

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: it answers factual questions by routing them to one of 5,462 tools across 1,419 sources, returning structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and provides concrete example questions.

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

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

The description explicitly instructs users to prefer this tool over web search and says 'START HERE' as the default entry point. It gives specific step-up conditions for alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, and also notes how it handles breaking news.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable context: that routing improvements may be live, none is currently active, and it fully matches ask_pipeworx right now. It also clarifies it is a full working router, not a fallback stub.

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 bit verbose but front-loads the key purpose and current state. Each sentence adds information: beta status, identical behavior, current inactive candidate, and usage guidance. It could be tighter but remains efficient for the complexity.

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

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

For a complex router tool with no output schema, the description effectively conveys the experimental nature, relationship to the stable router, and current equivalence. It gives the agent enough context to decide when to use it and what to expect.

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

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

The input schema already documents the 'question' parameter and all aliases with 100% coverage. The description does not add parameter-level detail beyond noting 'same arguments as ask_pipeworx', so it does not compensate beyond the schema 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 this is a beta version of ask_pipeworx, a universal router for the same 5,462 tools with the same arguments and response shape. It distinguishes from the sibling 'ask_pipeworx' by emphasizing the experimental routing improvements and current inactive status.

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

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

The description says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains the experimental context and comparison against the stable router. It provides clear context but does not explicitly state when not to use it.

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

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

Beyond annotations, the description reveals the extra LLM call, routing behavior across 5,462 tools, refusal mechanisms with specific refusal_reason values, and return object fields. No contradiction with readOnlyHint.

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

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

The description is dense but well-structured, front-loading the essential purpose and then providing mechanical and usage details. Each sentence adds value, and the length is justified by 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 explicitly defines the success and refusal return shapes. It also covers cost, alternatives, and high-stakes use cases, making it self-contained for an agent.

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

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

Input schema covers 100% of parameters with descriptions, so description adds no parameter-specific meaning. The description mentions filling arguments generically but does not detail individual parameters.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode that extracts answers using only tool result content, distinct from ask_pipeworx. It names the specific resource (answer extraction) and contrasts with sibling tool.

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

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

Explicitly states when to use: when answers will be quoted, cited, or acted on, and must not invent facts. Also explicitly prefers ask_pipeworx for casual lookups due to extra LLM call cost.

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?

Extensive detail beyond annotations: explains market resolution, classification, fan-out, response shapes (market, analysis, evidence), safety features (low-confidence short-circuit, closed markets, wide spreads), and resolution-rule risk (cancellation_rule). 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?

Well-structured with sections but lengthy. Each sentence adds value, but could be more concise. However, the detail is warranted for a 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 response shapes, resolver contract, parent events, news fields, safety, and resolution-rule risk. Handles edge cases like low-confidence, closed markets, wide spreads, and GDELT rate limits. Complete despite 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?

Adds significant meaning beyond schema: clarifies market param accepts slug, URL, or question; explains depth parameter (quick vs thorough); details include_raw usage (when to pass true). Overall very helpful.

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 it researches a Polymarket bet by pulling Pipeworx data in one call. Provides specific input types (slug, URL, question text) and use cases ('should I bet on X', 'what does the data say about Y'). Distinguishes from sibling tools by focusing on general research rather than edge/arbitrage.

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

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

Explicit use cases given ('Use for...'), but no mention of when NOT to use it or alternatives like polymarket_edges or polymarket_arbitrage. Clear context but lacks 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?

Even though annotations already declare read-only and idempotent behavior, the description adds rich detail: for companies it pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal-year handling, and for drugs it pulls FAERS, FDA, and trial data. It also explains sorting and output citation URIs.

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

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

The description is well-structured, starting with example triggers, then stating the core action, followed by type-specific details and output. It is slightly verbose but every sentence contributes 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?

The description adequately covers the tool's complexity by explaining the two entity types and their data sources. Although no output schema exists, hints about paired data and citation URIs provide sufficient context. It could be more detailed about exact return fields but is generally 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%, so baseline is 3. The description adds meaningful context beyond the schema by specifying that company values are tickers/CIKs and drug values are names, and by detailing what data is fetched for each type. This goes beyond the schema's parameter 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 performs side-by-side comparison of 2-5 companies or drugs in a single call, with specific example queries. It distinguishes itself from sequential lookups by explicitly noting it replaces 8-15 individual calls.

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

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

The description provides explicit guidance on when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists trigger phrases like 'compare X and Y' and 'X vs Y', making it easy for an agent to decide.

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

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

Adds substantial behavioral context beyond the annotations (readOnly, openWorld, idempotent): account and plan requirements, latency expectations (15-60s, up to ~90s), gap[] and contradictions[] behavior, citation_uri guarantee, semantic excerpting, and a 'never invented' claim. No contradiction with annotations.

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

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

The description is dense and long, but every section earns its place by covering auth, use cases, exclusions, output format, and performance. It is organized logically though not broken into paragraphs, which slightly hurts readability. The length is justified for a complex tool, so it does not warrant a lower score.

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 discloses return structure (findings packet, verbatim evidence, confidence, source, fetched_at, citations), gaps[], contradictions[], hop field, and edge cases like news topics returning mostly empty gaps. Also covers authentication, pricing, latency, and semantic excerpting, making it highly 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?

The input schema already provides detailed descriptions of both parameters (question and depth), including facet counts and hop behavior, achieving 100% coverage. The description adds a bit of extra nuance (e.g., latency per depth), but mostly restates schema content, so it holds at the baseline of 3.

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

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

The description clearly states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in a single call, with explicit detail about decomposing questions into facets and routing to parallel tools. It also distinguishes from sibling tools by contrasting with ask_pipeworx and clarifying it is not open-web search.

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 guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use with named alternatives ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also specifies account/tier prerequisites and a fallback if not signed in.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, and that results are ready to call directly. This provides useful behavioral context beyond annotations.

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

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

The description is fairly long but every sentence adds value. It front-loads the purpose and usage. Could be slightly more concise, but it is well-structured and informative.

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

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

For a tool discovery tool, the description is complete: it explains what it returns (tools with schemas), when to call it first, what domains it covers, and default/max limits. No output schema exists, but description adequately describes the return format.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning by explaining the 'query' parameter accepts natural language and provides examples ('analyze housing market trends'), and notes multiple aliases. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set.' This is a specific verb+resource with strong differentiation.

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

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

The description explicitly says when to use: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies this is for exploration rather than getting a single answer, though it does not explicitly state when not to use it.

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

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

Annotations (readOnly, openWorld, idempotent) are supplemented with rich behavioral details: fans across SEC, XBRL, USPTO, news, GLEIF; patents sunset May 2025 and soft-fails; GDELT→GNews fallback; response fields enumerated. 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 long but every sentence provides necessary context. Front-loaded with example queries. Some redundancy in listing return fields, but well-organized and actionable.

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

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

With no output schema, description fully explains return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Also covers fallbacks and limitations (patents sunset, no names support). Complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds beyond schema by clarifying 'Names not supported — use resolve_entity' and explaining ticker vs CIK usage. Adds practical guidance.

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 uses specific verbs and resources: 'full cross-source profile', 'ALWAYS PREFER over chaining...'. Examples like 'Tell me about X' make intent crystal clear. Distinct from siblings like resolve_entity.

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 prefer this tool over chaining for holistic views. States when NOT to use (when only have a name) and directs to resolve_entity first. Provides clear decision context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows it's a delete operation. The description confirms deletion but doesn't add new behavioral context like error behavior or key existence handling.

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

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

Two sentences: first states core action, second provides usage guidelines. Every sentence adds value, no redundancy, and information is front-loaded.

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

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

For a simple tool with one parameter, high annotation coverage, and no output schema, the description covers purpose, usage guidelines, and pairing with siblings, making it complete.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key' which is a specific verb and resource. It clearly distinguishes from siblings like 'remember' and 'recall' by mentioning them in the pairing advice.

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: context stale, task done, or clearing sensitive data. Also advises pairing with 'remember' and 'recall', providing clear context for 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 safe read-only, idempotent, non-destructive behavior. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, plus notes the output is a single text blob. No contradictions.

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

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

Three sentences, front-loaded with purpose, then how it works, then use cases. No redundant or filler content.

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?

Simple tool with 2 parameters and good annotations. Description covers purpose, behavior, output format, and use cases. No gaps remain for agent selection and invocation.

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

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

Schema coverage is 100% with both parameters described. Description does not repeat parameter details but adds context about fetching and extracting, which clarifies the url parameter's role. Baseline 3 is appropriate as schema already covers 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?

Description clearly states 'Generate a production-ready llms.txt file for any URL', providing a specific verb and resource. Differentiates from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing solely on generating the standard file 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 lists use cases: getting a client's site indexed, drafting for own project, auditing competitors. Does not mention when not to use or alternatives, but the listed use cases provide clear 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, ensuring safe read-only behavior. Description adds value by itemizing the exact schema elements returned (fields, geometry type, count, capabilities), which annotations do not cover.

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

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

Single sentence with no redundancy. Verb and key information are front-loaded. Every word is necessary and provides value.

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

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

Given the tool's simplicity (one parameter, no output schema needed, annotations covering safety), the description fully informs what the tool does and returns. No gaps remain.

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

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

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

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

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

Description specifies verb 'Get' and resource 'ArcGIS Feature/Map Service layer's schema', listing returned fields (name, type, geometry type, count, capabilities). This clearly distinguishes it from sibling tools like 'query_layer' which likely queries data.

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

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

The description implies usage for getting schema by URL but provides no explicit guidance on when to use this tool vs alternatives such as 'query_layer' or 'search_datasets'. No when-not or context exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields detail and default 'active' filter, but doesn't add major behavioral insights beyond annotations.

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

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

Two sentences, no fluff. First sentence states purpose and output format, second gives usage guidance. Front-loaded.

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

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

Given annotations and schema coverage, description covers purpose, usage, and output adequately for a simple list tool. No output schema needed since fields are described.

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 parameter fully (100%). Description doesn't add new meaning; it only reinforces that active subscriptions are listed by default. Baseline 3 appropriate.

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

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

Description clearly states verb 'List' and resource 'subscriptions', specifies scope 'caller's active', and lists returned fields. Distinguishes from sibling tools like subscribe/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 suggests using before adding more subscriptions or to find id for cancellation. Lacks explicit when-not-to-use but is sufficient context.

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

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

The annotations are all false, so the description carries full responsibility for behavioral transparency. It discloses important traits: the claim_token mechanism for later status checks, rate limiting ('Rate-limited to 5 per identifier per day'), that it is free and 'doesn't count against your tool-call quota,' and that the team reads digests daily. This exceeds what annotations provide and gives the agent a clear picture of side effects and constraints.

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

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

The description is longer than average but every sentence adds value: purpose, usage exclusions, instruction to not paste user prompts, claim_token mechanics, rate limits, and cost. It is front-loaded with the core purpose and structured logically from 'what' to 'when' to 'how.' No fluff or redundancy is present.

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 simple but nuanced feedback-capture responsibility, the description is fully complete. It covers all behavioral aspects (claim token, rate limit, cost), instructs on not including user prompts, and provides a clear disambiguation rule for when not to use it. There is no output schema, so the description adequately compensates by explaining what to expect from a filing and how to follow up.

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 documents all four parameters with 100% coverage, so the baseline is 3. The description adds extra meaning by explaining the claim_token workflow in detail ('Filing without an account returns a claim_token; pass it back later...') and contextualizing the 'type' values within a real usage scenario. It does not repeat the schema verbatim, instead enriching the semantics with operational 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's scope with concrete categories (bug, feature, praise) and explicitly distinguishes it from sibling tools by clarifying it is only for feedback about Pipeworx tools, not for general questions or other MCP servers.

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 guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: 'if the tool came from a different MCP server... file it with that server instead.' This covers both inclusion and exclusion criteria, making it easy for an agent to decide when to invoke the tool.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description adds: data is aggregated from CF analytics-engine, no PII, cached 5min-1h, and returns top tools/packs/volume. This gives helpful context but doesn't cover error handling or empty results.

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 are front-loaded: core functionality, three use cases, then data source and caching details. No redundancy, 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?

For a simple one-parameter tool with annotations covering safety, the description explains output composition, data provenance, privacy, and caching. Missing exact output schema but sufficient for selection.

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

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

The schema fully describes the window parameter with enum and description. The description adds semantic nuance about window choice (shorter windows show hot trends, longer show steady-state demand), which aids selection.

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 trending tools, packs, and call volume over a window. It uses specific verbs and resources, and distinguishes from siblings like discover_tools by focusing on aggregation of other agents' usage.

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, confirming canonical tool, aligning use case). Window selection guidance is given. However, it does not mention when not to use or directly reference sibling alternatives.

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

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

Annotations declare it read-only and safe. The description adds extensive behavioral context: internal scanning, monotonicity checks, partition filtering, semantic similarity thresholds, and fill check integration. No contradictions.

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

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

The description is comprehensive but verbose, containing multiple paragraphs with detailed algorithmic explanations. While well-structured, it could be more concise to reduce cognitive load.

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 response structure, including fields like gap_pp, suggested_trade, and partition_check. It covers all modes, thresholds, and edge cases (e.g., placeholder filtering, fill check), leaving no gaps.

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

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

Schema descriptions already cover both parameters, but the description enriches them with usage recommendations, examples, and explanations of how each mode works, adding significant value beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage specifically.

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

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

Provides explicit guidance on when to use no args, event, or topic, with examples and recommendations. Also explains when not to trade (fill check failure), aligning with best practices.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds significant behavioral detail: caching at KV level keyed on all knobs, edge calculation specifics (e.g., slippage, Kelly fractions, 24h-move warning), and response structure including diagnostics. 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 long but well-structured with clear sections. It is front-loaded with purpose and detailed later. Some redundancy exists (e.g., repeated mention of tradeable-edge filters), but overall it is efficient given the complexity.

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

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

For a tool with 9 parameters and no output schema, the description is remarkably complete. It explains cache behavior, response top-level structure, diagnostic information, and edge calculation details. This compensates for the missing output schema and ensures the agent understands what to expect.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds extra context, such as explaining why min_kelly does not filter partition arbs and how min_partition_leg_kelly applies instead. This goes beyond the schema, enhancing understanding.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It is tailored for 'what should I bet on today', and the detailed breakdown of segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides extensive usage guidance, including tradeable-edge knobs (min_liquidity, max_spread_pp) and filtering options. It explains how to interpret results and debug empty segments via _diagnostics. However, it lacks explicit when-not-to-use or comparisons with alternatives like polymarket_edge_tracker for historical analysis.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context: reads from snapshots, decay computed from daily closes, snapshots on cache-miss, gaps mean no scan. 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 lengthy but well-structured with front-loaded key question and bullet-like breakdown of response fields. Every sentence adds value, though it could be more concise.

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

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

Despite lacking an output schema, the description explains the return structure (tracked, expired, snapshot_dates) and key fields (trend, decay_pp_per_day). It also covers limitations like TTL bounds and snapshot gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default values, clamping, and explains 'window' as a snapshot family, providing nuance beyond the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series rather than current snapshots.

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

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

The description explains when to use the tool (to assess edge persistence and decay) and provides context like the implications of a 3-week-old edge. It does not explicitly mention alternatives or when not to use, but the limits (TTL, snapshot gap) are given.

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

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

Adds significant behavioral context beyond annotations: describes walking the order book ladder, return fields (top_of_book, VWAP, slippage, etc.), and crucial risk of unhedged directional positions from partial basket fills. Annotations already indicate readOnly, idempotent, openWorld, and non-destructive; description enriches with operational details.

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 bolded sections and line breaks; front-loaded with core purpose. Despite length, every sentence adds value given the complexity of two modes and many return fields. Could be slightly trimmed 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?

Comprehensively covers both single-market and basket modes, lists all return fields, explains the risk of partial fills, and includes usage thresholds. With no output schema, the description fully equips an agent to understand inputs, outputs, and potential pitfalls.

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 4 parameters have 100% schema description coverage, but the description adds meaning: clarifies market vs event modes, explains side defaults and interpretations, and defines size_usd for basket as settlement notional (shares per leg). This goes beyond the schema.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live order-book depth. Distinguishes from sibling tools polymarket_arbitrage and polymarket_edges by explicitly recommending use 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?

Provides explicit when-to-use guidance: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above $500. Also explains why (theoretical overround may not be capturable, partial fills cause directional risk).

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, idempotentHint, and destructiveHint=false. The description adds extensive behavioral detail: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the real information about non-equivalent bet shapes. 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 verbose but well-structured: introduction, modes, response format, safety fields. Every sentence adds value, though some elaboration could be tightened. Front-loaded with the core purpose.

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

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

No output schema, but the description explains response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross counters). Given the tool's complexity, it provides sufficient completeness for an agent to understand behavior.

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

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

Schema coverage is 100% (baseline 3). The description adds value by explaining the topic values list, how explicit tickers override mapped ones, and provides examples. 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 precisely states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by specifying the venue pair and framing.

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 two usage modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics currently return compatibility_warning, advising that pre-mapped ≠ tradeable. It does not explicitly name alternative tools for non-working cases, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns attribute rows and geometry, which is useful but not comprehensive. 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?

Two sentences: first defines purpose and lists parameters, second gives a usage tip. No wasted words, front-loaded with essential information.

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

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

Given detailed schema and annotations, the description is largely sufficient. It covers purpose, parameters, and a usage example. However, without an output schema, it could briefly mention the expected structure of returned rows (e.g., JSON format) for completeness.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by summarizing SQL-like syntax and providing a concrete sample use case (where='1=1', out_fields='*'), making it easier to invoke correctly.

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 it queries an ArcGIS Feature/Map Service layer by URL, listing key parameters. It distinguishes itself from sibling tools like search_datasets (which finds datasets) by explicitly referencing 'from search_datasets' as the source of the 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 context: use after search_datasets, and includes a practical sampling tip (where='1=1', out_fields='*'). However, it does not explicitly state when not to use this tool or compare it to other query-related siblings like layer_info or search_within.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping to agent identifier and behavior when key omitted. No contradictions.

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

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

Two sentences, front-loaded with main action. Every sentence adds value with no redundancy.

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

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

Simple tool with one optional param, no output schema, good annotations. Description covers behavior, scope, and sibling relationships fully.

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 context that key is a 'memory key' and clarifies omission lists all keys, adding value beyond the schema.

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

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

The description explicitly states the verb 'retrieve' and resource 'value saved via remember', and lists key use cases like ticker, address, research notes. It clearly distinguishes from siblings remember and forget.

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

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

The description says when to use (look up context stored earlier) and mentions pairing with remember, forget. Does not explicitly exclude alternatives, but context is clear.

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

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

Annotations indicate idempotent and read-only behavior; description adds crucial detail about 'mark_read:true' mutating state for subsequent calls. No contradictions with annotations.

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

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

The description is a single compact paragraph (~100 words) with clear progression: purpose, return fields, parameters, alternative access. 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 covers return fields, filtering, mark_read behavior, polling suitability, and an alternative endpoint. Lacks error handling details, but the tool is simple and annotations cover safety.

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

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

Schema coverage is 100%, and the description adds value by explaining parameter usage with examples (e.g., 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)'), exceeding the baseline of 3.

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

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

The description uses specific verbs ('Pull', 'Returns') and clearly identifies the resource ('fired events from your subscription feed', 'most recent alerts'). It distinguishes itself from sibling tools by focusing on alerts/events rather than subscriptions or other 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?

Explicitly states that 'Polls work fine' and provides an alternative access method (GET endpoint for scripts/dashboards), implying when to use this tool vs. the HTTP endpoint. However, it does not explicitly exclude alternatives like 'list_subscriptions'.

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, and non-destructive. The description adds detailed behavioral context: data sources (SEC EDGAR, GDELT/GNews fallback, USPTO), rate-limiting behavior, soft-fail for USPTO, and the return structure (changes grouped by source, total changes, 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 a single, well-structured paragraph that includes examples, fallback behavior, and usage guidance without redundancy. Every sentence adds value, making it concise yet informative.

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

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

Given the complexity of the tool (multiple data sources, fallback logic, relative date handling), the description covers all essential aspects: source behavior, rate-limiting fallback, parameter formats, and return structure. No output schema exists, but the description sufficiently outlines the output shape.

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 descriptions. The description adds value by explaining 'since' accepts ISO date or relative shorthand with example ('7d', '30d', '3m', '1y') and suggests '30d' for typical monitoring. It also clarifies that 'value' accepts ticker or CIK. Though schema already describes, the description enriches 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 provides a change feed for a company in a time window, aggregating from multiple sources. It contrasts with the sibling tool 'entity_profile', which offers static profiles, thus clearly distinguishing its purpose.

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

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

The description explicitly tells when to use this tool vs. alternatives by directing users to 'entity_profile' for static profiles. It also provides example queries, making it clear when this tool is appropriate.

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

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

Discloses that storage is key-value scoped by identifier, with retention details (persistent for authenticated users, 24 hours for anonymous). This goes beyond annotations (idempotent, non-destructive) and adds crucial behavioral context.

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

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

Three concise sentences front-load purpose, then usage, then storage details. No unnecessary words; every sentence adds value.

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

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

Fully complete for a simple key-value store tool with 2 required params and no output schema. Covers purpose, usage, storage behavior, and companion tools.

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

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

Schema covers both parameters with descriptions. The description adds example key patterns (e.g., 'subject_property') and value types, providing extra semantic meaning beyond the schema alone.

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

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

The description clearly states the tool saves data for reuse across conversations, with specific examples like 'resolved ticker' and 'target address'. It differentiates from siblings by mentioning recall and forget as companion 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 tells when to use: 'when you discover something worth carrying forward'. Also provides alternatives: 'Pair with recall to retrieve later, forget to delete', offering clear contextual 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond annotations: it mentions internal cascading lookups, auto-disambiguation, and citation URIs in the return. This helps the agent understand side effects and reliability 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 front-loaded with natural-language examples and a clear core sentence. It is somewhat dense with return-field details, but every sentence provides useful guidance. Overall it is well-structured and not bloated.

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 thoroughly explains return values for both supported types, including citation URIs. It also conveys the internal cascade behavior and positions the tool relative to manual lookups. This is complete for the agent to anticipate results and side effects.

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

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

Schema coverage is 100%, so the description doesn't need to compensate. It does restate the enum values and input formats, adding a note about auto-disambiguation, but it doesn't significantly enrich parameter semantics beyond the schema's existing 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: resolving user-spoken names to canonical/official identifiers required by other tools. It uses specific verbs ('resolve', 'look up') and distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and input formats. It does not explicitly name alternative tools for when not to use it, but the instruction 'FIRST' strongly implies the intended workflow.

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

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

The description adds behavioral context beyond annotations: it explains that the tool calls 'ai_visibility_check' for each entity, ranks results, and returns score/confidence/signal density. Annotations already declare read-only, open-world, idempotent, non-destructive, so the description complements well without contradiction.

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

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

The description is concise (4 sentences), front-loaded with the core action, and every sentence provides essential 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?

Despite lacking an output schema, the description fully explains what is returned (ranked list with specific fields). It covers purpose, usage, and all parameter nuances, leaving no critical gaps.

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

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

Schema coverage is 100%, and the description adds significant meaning: it explains that the first entity in 'entities' is treated as the subject, gives default model behavior, and clarifies that 'context' disambiguates common names. This aids correct invocation.

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

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

The description uses specific verbs (compare, probes, ranks) and resource (competitor AI presence). It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the multi-entity competitive audit 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 explicitly states it is useful for competitive AI-marketing audits and provides an example question. While it does not list explicit alternatives or exclusion criteria, the context and example imply when to use it versus single-entity tools.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds key behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts. No contradiction with annotations.

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

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

Description is detailed but each sentence adds valuable context. Front-loads composite nature. Could be slightly more concise but not verbose relative to information density.

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 specifies return structure: summary block, per-advisory detail, links, alternative versions. Covers graceful degradation and limitations. Complete for a composite tool with two external sources.

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 description adds limited value. It confirms scoped packages accepted and version defaults to latest, matching schema. Baseline 3 is appropriate as schema already fully documents parameters.

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 specifies a composite check for npm packages covering license, advisories, version history, and bundle size. It clearly distinguishes from siblings by noting NPM ecosystem only in v1 and directing to deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes exclusions: PyPI/Maven/Cargo/Go fall under deps.dev:version directly.

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, destructiveHint, openWorldHint, and idempotentHint. The description adds the return structure (name, summary, record_count, owner/org, url) and the intended downstream usage, which is helpful beyond annotations. No contradictions.

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

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

Two sentences that front-load the action and domain, then provide essential details. No redundant words, every sentence adds value.

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

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

The description explains what the tool returns and how to use the results with sibling tools, and mentions the optional org_id. It does not cover pagination or sorting behavior, but given the schema has a limit parameter, this is acceptable.

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 each parameter having a description. The tool description adds no significant additional parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches City of Toledo GIS datasets by keyword, lists exactly what is returned (name, summary, record_count, owner/org, feature service URL), and distinguishes from sibling tools by instructing to pass the URL to query_layer/layer_info.

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 (search by keyword) and provides downstream guidance (pass URL to query_layer/layer_info). Does not explicitly state when not to use, but the sibling context and domain scope ('City of Toledo GIS open geospatial datasets') imply boundaries.

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

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

Description provides extensive behavioral details beyond annotations: max 200K chars with truncation flag, BGE-base-en embeddings, 500-char overlapping windows, and return of offsets/scores. Aligns with readOnlyHint, idempotentHint, and destructiveHint.

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 concise yet comprehensive, front-loaded with purpose and usage, then technical details. Every sentence adds value; no redundancy.

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

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

Given no output schema, description appropriately explains return type (passages with offsets and scores). Parameters are well-covered, and annotations provide safety context. The description is fully adequate for agent use.

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

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

Schema coverage is 100%, baseline 3. Description adds value by clarifying max length for 'text', providing examples for 'query', and specifying default and range for 'limit', exceeding schema details.

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

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

Description clearly states it performs semantic search inside a retrieved document, uses specific verbs ('search inside', 'get back'), and distinguishes from sibling tools by referencing pairing with 'ask_pipeworx_grounded' and noting when to use.

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 usage context: 'Use when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded'. Does not explicitly list when not to use, but context is clear.

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

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

Discloses key behaviors: requires OAuth account, phone verification needed for SMS, 10/day SMS cap, webhook auto-disable, and returns subscription id. Does not clarify idempotency (e.g., re-subscribing with same params) despite idempotentHint=true.

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

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

Efficiently structured with bullet points for types and delivery channels. Every sentence adds value; no redundant 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?

Covers 3 of 5 enum types in depth; patent_grant and clinical_trial are omitted. No output schema, but returns subscription id is stated. Missing error handling and rate limit details beyond SMS cap.

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

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

Schema coverage is 100%, so baseline is 3. Description adds examples and constraints for type-specific params (e.g., ticker, topics) and delivery channels (SMS cap, webhook HMAC signing), exceeding schema detail.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention for subscribing vs. managing subscriptions via list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral context: the return format (category-bucketed example questions with exact tool+argument shapes) and that it's the onboarding entry point. 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 moderately long but well-structured, starting with common user queries ('What can I ask Pipeworx?') and then explaining functionality and usage. Every sentence adds value, though slight redundancy in listing categories twice could be trimmed.

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

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

For a simple tool (1 optional param, no output schema), the description is exceptionally complete: it explains the purpose, when to use, what it returns, how to invoke with or without topic, and even mentions that it draws from a live catalog of thousands of tools.

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

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

Schema coverage is 100% for the single optional 'topic' parameter. Description adds significant meaning: omitting topic gives full spread, passing a specific topic focuses on that area, and lists valid examples like 'finance', 'pharma'. This goes beyond the schema's generic description.

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

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

Description explicitly states the tool returns category-bucketed example questions, lists specific categories, and distinguishes it as the onboarding entry point for new agents. Sibling tools like ask_pipeworx or deep_research are clearly different.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also mentions alternatives (meta-tools like ask_pipeworx, entity_profile) and optional topic parameter to focus.

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 key behavioral details beyond annotations: ownership enforcement and deactivation (not deletion) with historical events available via recent_alerts. Annotations only hint at non-destructive and 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?

Three short, focused sentences with no redundancy. Each sentence provides essential information.

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

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

For a simple tool with one parameter and no output schema, the description fully explains purpose, behavior, and side effects. The coverage is 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?

The schema already describes the 'id' parameter. The description adds that ownership is enforced, providing context on how the parameter is validated.

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 cancels a subscription by ID, distinguishing it 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?

It mentions ownership enforcement (only cancel your own) and explains the row is deactivated not deleted, providing context for use. It does not explicitly list alternatives but the purpose is clear.

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

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

The description adds significant behavioral context beyond the annotations. It details the return values (verdict, actual value with citation, reasoning), explains the two verification paths (fast path for financial claims, grounded pipeline for others), and describes the idempotent and read-only nature implied by annotations. 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 efficiently structured, starting with natural-language triggers, then usage guidance, followed by detailed operation and return values. Every sentence adds value without redundancy.

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

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

Given there is no output schema, the description fully explains the return values (verdict types, citations, reasoning). It also covers the tool's logic, when to use, and how it differs from alternatives. Complete for a two-parameter tool with 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?

The input schema covers 100% of parameters with descriptions. The tool description adds meaning beyond the schema by explaining how 'tolerance_pct' overrides the implied tolerance and suggesting use cases (1-2% for hallucination detection). This enhances understanding.

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

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

The description clearly defines the tool's purpose: verifying natural-language factual claims against authoritative sources. It provides specific verb ('validate') and resource ('claim'), and distinguishes itself from sibling tools by detailing its unique functionality, including the two-path routing for financial vs. other claims.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two verification paths and mentions that it replaces multiple sequential calls. While it does not explicitly state when not to use it, the guidance is clear and sufficient.

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