Arcgis Cranston

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral details: default model is Workers AI Llama-3.3-70b (free), Anthropic requires a BYO API key, and output includes per-model score, confidence, signals, raw_response. 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 concise (3 sentences) and well-structured. The first sentence delivers the core action and output, followed by details on defaults and returns. 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?

Although there is no output schema, the description adequately describes return values: per-model {score, confidence, signals, raw_response} plus a combined view. It covers all parameters and behavior, but the lack of explicit return format for the combined view is a minor gap.

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

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

Schema coverage is 100%, but the description adds value beyond the schema by explaining the default model, the role of the API key, and the purpose of the 'context' parameter for disambiguation.

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

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

The description uses a specific verb ('probe') and resource ('LLMs') to define the tool's action, and clearly states the output ('score visibility 0-100 per model'). It differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on probing multiple AI models for brand knowledge.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly list when not to use or alternatives, but the context signals and sibling tool list provide enough differentiation.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds that it routes to 4,552 tools and returns structured answers with citation URIs. No contradictions. Misses mention of error handling or rate limits, but annotations cover the safety profile well.

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

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

The description is relatively long but well-structured with examples, usage guidance, and sibling differentiation. Every sentence adds value, though it could be slightly more concise by grouping examples more tightly.

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

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

Given no output schema, the description explains the return type (structured answer with citation URIs). It covers the tool's scope comprehensively. However, it doesn't specify behavior on errors or empty results, which would improve completeness for a complex tool with many parameters.

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

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

Schema coverage is 100% with all 6 parameters documented (including aliases). The description adds context that the question should be in natural language, but doesn't provide additional semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is for asking questions about current/historical data across many domains (SEC filings, FDA drugs, etc.), and contrasts with siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' plus the extensive list of use cases makes the purpose specific and distinguishable.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides when-to-use guidance with examples of factual questions. It also tells when to step up to grounded or deep_research, covering exclusions. This is a model of usage guidelines.

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 behavioral traits beyond annotations: returns refusal reasons when data insufficient, costs an extra LLM call, and extracts answer only from tool result. 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?

Concise paragraph front-loaded with purpose and key behavior, followed by routing, output format, and usage guidance. Every sentence adds value.

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

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

Given no output schema, the description fully explains return values including refusal reasons. Covers purpose, behavior, cost, and usage, making it complete for high-stakes 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% with clear parameter descriptions for all aliases. The description does not add new semantic information beyond what the schema provides, meeting baseline but not exceeding.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling 'ask_pipeworx' by specifying it extracts answers only from tool results, providing a specific verb and resource.

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 answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), citing cost and risk of invention.

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, non-destructive. The description adds extensive behavioral context: fan-out process, classifier list, response shapes with specific fields, resolver contract (confidence, alternatives, suggestions), parent event extractor, news fallback, safety mechanisms (low-confidence short-circuit, market_closed_or_inactive), illiquidity warnings, and cancellation rules. No contradiction with annotations.

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

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

Front-loaded with purpose and input format. Uses clear section headers (CAPS) for topics. Every sentence adds value, but the description is long (~800 words). Could be slightly more terse, but all information is relevant and well-organized.

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 is remarkably complete. It details all major response components (market, analysis, evidence, resolver, parent_event, news), error states (low_confidence_match, market_closed_or_inactive), edge cases (wide spreads, cancellation rules), and safety measures. An agent has sufficient context to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for market, depth, and include_raw. The description adds significant extra meaning: examples for market input (slug, URL, question text), depth enumeration explained ('quick' vs 'thorough' with evidence source counts), and include_raw with advice on when to use (summarized vs full payloads).

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymorphic_arbitrage and polymorphic_edges by being the comprehensive research tool that fans out to data sources.

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

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

Explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also warns when not to trust results (low-confidence matches short-circuit, closed markets return blocking status) and instructs to inspect market_match_confidence before trusting 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 it as read-only, idempotent, and non-destructive. The description adds significant behavioral context: what data is pulled for each type (financials, adverse events), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in the response. No contradiction.

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

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

The description is concise (about 8 lines) and front-loaded with example queries. Every sentence provides useful information: examples, preference statement, data sources, sorting, return format, and efficiency gain. No redundant or missing information.

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

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

Given the tool's complexity with two entity types and different data sources, the description covers all necessary details: what data is returned for each type, sorting behavior, and citation format. No output schema exists, but the description sufficiently explains the response structure. The annotations cover safety and idempotency, making the tool well-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 coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples (e.g., tickers for company, drug names) and explaining the implications of the type parameter (what data is fetched). This enhances the agent's 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 purpose: side-by-side comparison of 2–5 companies or drugs. It provides example user queries and distinguishes itself from single-lookup siblings by explicitly recommending its use over sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong guidance on when to use this tool. It also explains the data retrieved for each type and how results are sorted, helping the agent choose between this and alternative tools like entity_profile.

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

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

Annotations (readOnlyHint=true, etc.) are present and consistent. Description adds important context: account requirement, paid plan for 'thorough' depth, never invents data (gaps[]), and expected timing (15-60s). Does not discuss rate limits or error details, but overall adequate.

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

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

Description is dense with essential info (account requirement, alternatives, capability, limitations, output format) and front-loaded. Slightly long but every sentence contributes; could be more concise but still effective.

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

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

Given tool complexity (multi-source, multi-tool orchestration), description covers purpose, prerequisites, when to use/not use, behavior (gaps), timing, and output packet format. No output schema but return values explained sufficiently.

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

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

Schema has 100% coverage, and description adds meaningful context: explains depth enum meanings (quick=3, standard=5, thorough=8 paid) and clarifies question accepts natural language, broad/multi-part. Adds value beyond schema.

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

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

Description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' in one call, decomposes questions, and returns findings packet. Distinguishes from siblings like ask_pipeworx (single lookup) and specifies when each is appropriate.

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

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

Explicitly says 'Best for broad/multi-part questions over structured data' and provides clear when-not-to-use cases: breaking news topics (prefer ask_pipeworx) and unsigned-in users (use ask_pipeworx). Names alternative tools 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, idempotentHint, and destructiveHint as safe. The description adds value by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This goes beyond annotations and helps the agent understand the result structure.

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 structured with a clear purpose, usage guidance, and return value explanation. It is appropriately sized for the tool's complexity and front-loads the most important information. Minor redundancy (e.g., listing domains twice) could be trimmed, but overall effective.

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

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

Given the tool's complexity (6 parameters, no output schema, many siblings), the description covers all necessary aspects: what the tool does, when to use it, what it returns (with examples), and that it includes full schemas for direct calling. No critical information is missing.

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

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

Schema coverage is 100%, but the description adds meaning by explaining that 'query' accepts natural language and providing examples like 'analyze housing market trends.' It also mentions aliases (task, q, description, search), which adds clarity beyond the schema's property 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: 'Find tools by describing the data or task.' It uses specific verbs like 'browse, search, look up, or discover' and lists many example domains. This distinguishes it from sibling tools, which are specialized operations, by positioning discover_tools as the meta-search tool.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set,' providing clear when-to-use guidance. While it doesn't explicitly state when not to use, the context implies it's for exploration, not for a single answer. This is sufficient for most agents.

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

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

Discloses parallel fan-out across sources, return fields, and a known soft-failure for patents ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). Annotations already idempotent/read-only; description adds meaningful operational context 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?

Front-loaded with examples and concise in listing return fields. Slightly long due to thoroughness, but every sentence adds value. Could trim some internal notes, but well-structured overall.

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

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

Given the tool's complexity (multi-source, fallback, no output schema), the description covers inputs, outputs, edge cases (patents soft-fail), and naming constraint. User needs no additional context to select or invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions. The description adds critical format rules: zero-padded CIK, ticker without dollar sign, and explicit exclusion of names. This goes beyond the schema's enum/type hints to clarify real usage.

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

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

The description starts with concrete usage examples like 'Tell me about X' and 'company profile for Microsoft', then defines the tool as a 'full cross-source profile of a US public company in ONE parallel call'. It lists all returned data types, clearly distinguishing this holistic tool from single-source siblings.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', and provides a when-not-to-use condition: 'names not supported (use resolve_entity first if you only have a name)'. This gives clear guidance on 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 provide destructive and idempotent hints. The description adds minimal extra behavior—just 'delete by key.' It does not elaborate on error cases (e.g., key not found) or side effects. For a simple destructive operation, this is adequate but not enriching 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 very concise—three short sentences. It front-loads the core purpose and adds usage guidance and sibling references without any filler. Every sentence earns its place.

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

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

For a single-parameter tool with high schema coverage and clear annotations, the description provides sufficient context for usage. It does not detail return values or error behavior, but given simplicity, this is not critical. Slightly above average 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%, and the parameter description 'Memory key to delete' matches the tool description. The tool's description adds no extra semantic value beyond the schema, 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 'Delete a previously stored memory by key' with a specific verb and resource. It also distinguishes from siblings by mentioning pairing with remember and recall, making the tool's purpose unambiguous.

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

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

Explicit guidance provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This tells when to use and implies when not (e.g., if memory is still needed). The mention of pairing with remember and recall offers 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 readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: fetches page, extracts title/description/key links, emits markdown. 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 two sentences plus a bullet-like list of use cases. Every sentence is informative and front-loaded, with no wasted words.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, process, output format, and use cases thoroughly. It is self-contained.

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

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

Schema description coverage is 100%, but the description adds value with an example for url and explicit default/max for max_links. This clarifies parameter usage 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 generates a production-ready llms.txt file for any URL, specifies the input (URL), and output format. It distinguishes itself from siblings by focusing on AI crawler indexing and the llms.txt standard.

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 use cases: getting a client's site indexed, drafting for own project, or auditing competitor view. It lacks explicit when-not-to-use or alternative sibling names, 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, openWorldHint, idempotentHint, and destructiveHint false, indicating safe read-only behavior. The description adds specific details about the return contents (fields, geometry type, count, capabilities) beyond annotations, providing useful context about the tool's output.

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

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

The description is a single sentence with no extraneous words. It front-loads the action ('Get') and resource, making it efficient and easy to parse. Every word contributes meaning.

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 comprehensive annotations, the description adequately covers the tool's functionality and output. The absence of an output schema is compensated by listing the return elements. Some might prefer more detail on capabilities, but overall it is sufficient.

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

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

The single parameter 'url' is fully described in the schema (100% coverage). The description adds an example format ('.../FeatureServer/0'), which helps the agent understand the expected structure, surpassing the baseline score of 3.

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

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

The description uses a specific verb ('Get') and identifies the exact resource ('ArcGIS Feature/Map Service layer's schema'). It enumerates the returned items (fields, geometry type, record count, capabilities), making the purpose clear and distinct from siblings like 'query_layer'.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'query_layer'. The description lacks any 'when-not' context or mention of alternative methods, leaving the agent to infer usage without explicit direction.

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 return field details and default scope ('active') beyond the annotations' safety profile. Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description complements with useful behavioral context.

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

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

Two concise, front-loaded sentences with no wasted words: first sentence covers purpose and return format, second provides usage guidance.

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

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

Adequately covers purpose, return, and usage for a simple read-only tool with rich annotations. Missing potential details like result limits, but not critical.

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

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

Schema has 100% coverage for the single parameter; description does not elaborate on the parameter's effect beyond implying default behavior. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions', specifying it returns active subscriptions and the exact fields. It distinguishes from siblings 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 advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', guiding the agent on when to use it relative to subscribe and 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?

Beyond the annotations (all false), the description discloses rate limits (5 per identifier per day) and that it does not count against tool-call quota. These are valuable behavioral traits not captured by annotations.

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

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

The description is front-loaded with the action and purpose. Each sentence adds necessary context (usage, limitations, formatting). It could be slightly more concise but remains efficient for its content 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?

Given the tool's simplicity (3 parameters, 1 enum, nested object) and lack of output schema, the description covers all essential aspects: purpose, when to use, parameter semantics, rate limits, and quota impact. An agent has sufficient information to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining each enum value for the 'type' parameter and providing concrete guidance for the 'message' field (be specific, 1-2 sentences). This enriches the schema.

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

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

The description explicitly states the tool's purpose: to send feedback about broken, missing, or needed items. It lists specific feedback types (bug, feature, data_gap, praise) and distinguishes the tool from siblings, none of which are feedback-related.

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

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

The description clearly indicates when to use the tool (for bugs, features, data gaps, praise) and advises against pasting end-user prompts. It does not explicitly state when not to use it, but the context is sufficient for an agent to infer appropriate usage.

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

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

Description adds caching behavior (5min-1h depending on window), self-aggregating signal, and no PII, going beyond annotations which already declare read-only, idempotent, non-destructive.

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

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

Four sentences, front-loaded with main purpose, then use cases, then technical details. No wasted words.

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

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

For a simple one-parameter tool, the description covers return values, caching, privacy, and usage context. No gaps.

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

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

Schema covers the single parameter fully with clear description; description adds context about short vs. long windows surfacing different trends.

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 returns top tools, top packs, and total call volume over recent windows, distinguishing it from siblings by focusing on aggregate trends from other agents.

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

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

Provides three explicit use cases (discovering hot data sources, confirming popular tool, seeing alignment) but lacks explicit when-not-to-use or alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: algorithm details (monotonicity, partition-sum), response structure, fill_check sub-step, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and edge cases. 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 lengthy but well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). Every sentence adds value, though some could be more terse. Still effective 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?

No output schema exists, yet the description covers the full response structure (opportunities[], partition_check, fill_check), references sibling tool for custom sizing, and explains key edge cases (skipped_low_similarity, placeholders). Complete for decision-making.

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

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

Schema description coverage is 100% with basic descriptions. The description adds significant value by explaining acceptable values for event (slug or full URL) and topic (seed question), with examples. Slightly more context than necessary, but still enhances clarity.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic), which differentiates it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Also explains cross-event vs single-event advantages, when to use fill_check, and warns against trading when realizable_edge_pp <= 0.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds extensive behavioral details: caching (1h KV-level), filtering logic, model families (FRED, GDELT), slippage assumptions, diagnostics, and edge calculation (net of slippage). It fully discloses how the tool works 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 well-structured with sections and parentheses but is quite dense and verbose. It front-loads the core purpose and then dives into technical specifics. While every sentence adds value, some details (e.g., exact model formulas) could be condensed. Still, it remains clear and organized.

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 (9 parameters, no output schema), the description is thorough. It explains the response structure (by_segment, diagnostics, Fed bets excluded), caching, and all key behaviors. It compensates for the lack of output schema by detailing what is returned. No gaps remain for an agent to use the tool effectively.

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

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

Schema coverage is 100% with clear descriptions. The tool description adds significant context for parameters like slippage_pp, min_liquidity, and min_partition_leg_kelly, including practical guidance (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). This enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan', the resource 'Polymarket markets', and the purpose 'what should I bet on today'. It also details three distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description implicitly indicates usage for discovering betting opportunities but does not explicitly state when to use this tool over alternatives like polymarket_arbitrage or polymarket_edge_tracker. No when-not-to-use or exclusion criteria are mentioned. However, the 'Built for' phrase gives some 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral details: returns tracked/expired/snapshot_dates, explains decay computation (daily closes, not intraday), and clarifies snapshot gaps due to cache misses.

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 purpose, but is fairly long due to detailed response explanation. Every sentence adds value, but could be more structured. Nonetheless, it remains clear and informative.

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

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

Given the complexity (time-series data, 2 optional params, no output schema), the description fully covers the response structure (tracked, expired, snapshot_dates) and limitations (TTL, cache-miss gaps). No critical information is missing for an agent to use the tool correctly.

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

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

Input schema already covers both parameters with descriptions (100% coverage). The description repeats default and max values, and adds context about 'snapshot family' for window, but adds marginal new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and decay, distinguishing it from sibling tools like 'polymarket_edges' which likely provides current edges only.

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

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

The description provides context on when to use this tool (to differentiate fresh vs old edges) and notes limitations (60-day TTL, cache-miss gaps). It does not explicitly contrast with siblings or state when not to use, but the context is clear.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds rich behavioral detail: walks order-book ladder, returns specific verdicts (clean|degraded|cannot_fill), and highlights forced directional risk in basket mode. No contradiction.

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

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

Description is thorough but well-structured with clear sections (single-market, basket, warning). Every sentence earns its place, though length could be slightly reduced; still excellent value 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?

Despite no output schema, description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, thin_legs, forced_directional_risk). Complete enough for an agent to understand inputs and outputs.

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

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

Schema coverage is 100%, but description significantly enhances understanding: explains default values, mode-dependent interpretation of size_usd (spend vs target proceeds vs settlement notional), and side auto-detection logic for baskets. Such enrichment adds real value.

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

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

Description starts with specific verb-resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes single-market vs basket modes and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why: theoretical overround may be uncapturable and partial fills create 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: compatibility_warning for non-equivalent bet shapes or semantically unrelated events, temporal_alignment for date mismatches, and skipped counters for metric/inequality mismatches. It also clarifies that spreads are meaningless without aligned resolution periods.

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 somewhat lengthy. It is well-structured with separate sections for modes, response, and safety fields, and key information is front-loaded. A few sentences could be condensed without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields) and covers edge cases like compatibility warnings, temporal misalignment, and skipped comparisons. It is complete for a complex cross-venue spread tool.

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

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

Schema coverage is 100% with descriptions on all 3 parameters. The description adds substantial value by explaining the two modes, listing all 10 topic shortcuts, and specifying that explicit parameters override topic mapping. Examples (topic: 'fed', topic: 'btc') clarify usage.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts or explicit tickers), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges which focus on single-venue analysis.

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

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

The description explains two modes and when to use each: topic shortcuts for common macro events, and explicit tickers for custom pairs. It warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. However, it lacks explicit comparison to siblings or guidance on when not to use this tool.

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

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

Annotations already indicate readOnlyHint and idempotentHint, which the description aligns with. It adds behavioral context: returns attribute rows and geometry, supports SQL-like syntax and pagination.

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

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

Two concise sentences with no fluff. Every word adds value, front-loading the core action and providing key examples.

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

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

The description covers the main purpose, parameters, and behavior. No output schema, but it explains returns. Could mention default limit more explicitly, but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by stating SQL-like syntax, comma-separated fields, and giving concrete examples (where='1=1', out_fields='*').

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 queries an ArcGIS Feature/Map Service layer by URL, with SQL-like filters. It distinguishes from siblings like search_datasets (for finding layers) and layer_info (for metadata).

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

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

The description implies usage context: URLs come from search_datasets. It provides examples like where='1=1' and out_fields='*'. While it doesn't explicitly list when not to use, the hints are 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details: scoping to user identifier (privacy/security) and the listing behavior when key is omitted. No contradiction with annotations.

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

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

The description is concise at three sentences, each adding critical information. The first sentence states the core function, the second provides usage guidance, and the third adds scope and pairing. No redundancy.

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

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

Given no output schema, the description explains the two possible outcomes (retrieved value or list of keys). It also covers scope, pairing with siblings, and provides examples. This is complete for a retrieval tool.

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

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

Schema coverage is 100% and schema description explains the parameter well. The description adds value by clarifying the dual behavior (retrieve vs. list) and giving concrete examples of key values, which aids understanding beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys when the key is omitted. It distinguishes from siblings by defining recall as retrieval, remember as save, and forget as delete. Concrete examples (ticker, address, research notes) solidify 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 says when to use recall ('to look up context the agent stored earlier... without re-deriving it from scratch') and pairs it with remember and forget. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable context: mark_read flag modifies state, polling is safe, and the feed is also available via a direct URL. 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?

Four concise sentences, each adding value: purpose, return content, filtering/mark_read, and polling/alternative access. Well-structured and front-loaded.

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

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

Given the tool's complexity (5 optional params, no output schema), the description covers: what it does, what it returns (with field names), how to filter, side effects of mark_read, and even alternative access. Minimal missing information.

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

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

Schema coverage is 100% (all parameters described). The description adds examples ('sec_8k'), clarifies mark_read behavior, and notes the default limit. This enriches understanding 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?

Clearly states 'Pull fired events from your subscription feed' and describes what each event carries (source, citation_uri, raw payload). The purpose is specific and distinct from siblings like 'subscribe' or '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?

Provides clear usage context: mentions polling is fine, gives an alternative access method (alerts.json), and details filtering options. However, it does not explicitly exclude use cases or contrast with sibling tools.

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

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

The description adds rich behavioral context beyond the annotations: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), describes the fallback mechanism, and notes that PatentsView soft-fails due to sunset. It outlines the return structure (changes[] grouped by source, total_changes count, citation URIs). The annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent with the described behavior, and no contradiction exists.

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 front-loaded with example queries that immediately convey purpose. It is well-structured with clear information about each data source and the fallback. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given the complexity of fanning out to multiple sources and the lack of an output schema, the description covers the major behaviors: return structure, source grouping, fallback, and a known limitation (PatentsView sunset). It could be improved by mentioning potential errors or rate limit details, but it is adequate for an agent to understand the tool's capabilities.

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

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

All three parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra value by explaining the 'since' parameter format with examples (ISO date or relative like '7d', '30d', '1y') and providing usage hints ('Use "30d" for typical monitoring'). It also clarifies that 'value' accepts ticker or zero-padded CIK. This additional guidance justifies a score above baseline.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, covering SEC filings, news (with GDELT/GNews fallback), and patents. Example queries ('What's new with X', 'latest on Y') make the purpose immediately understandable. It explicitly distinguishes from the sibling tool 'entity_profile' by noting when to use that instead.

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

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

The description gives explicit when-to-use guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' It provides best practices for the 'since' parameter ('Use "30d" or "1m" for typical monitoring') and explains the fallback behavior from GDELT to GNews on rate limits. It also notes the PatentsView sunset limitation, helping agents manage expectations.

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 persistence rules (24-hour for anonymous, permanent for authenticated) and scoping by identifier. No contradiction with annotations; idempotentHint is consistent.

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

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

Concise, front-loaded with main purpose, no wasted words. Efficiently conveys all needed info.

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

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

Complete for a simple key-value store: covers purpose, usage, persistence, and relationships to siblings.

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 little beyond schema examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations, with specific examples like ticker or preference. It distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Provides context on scoping and persistence, and pairs with recall and forget.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by noting that each call cascades through multiple internal endpoints, effectively replacing 2-3 manual lookups, which is useful behavioral context beyond the annotations.

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

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

The description is roughly 100 words, front-loaded with examples, and efficiently covers purpose, usage, and parameter details without unnecessary repetition. Every sentence adds value.

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

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

Despite lacking an output schema, the description details what is returned for each type (ticker+CIK+company name for company; RxCUI+ingredient+brand for drug) and mentions citation URIs. It is fairly complete, though missing error handling or not-found scenarios.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds significant context by detailing accepted inputs per type (e.g., ticker, CIK, or name for company; brand or generic for drug), which enhances understanding beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers for other tools, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings like 'compare_entities' and 'entity_profile' by focusing on name-to-ID resolution.

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

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

The description explicitly advises to use this tool 'FIRST whenever you have a name but need an ID' and provides example queries that trigger it. It does not explicitly state when not to use it, but the positive guidance is clear and sufficient given the context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond this: it reveals that the tool 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns a 'ranked list with score, confidence, signal density per entity.' This explains internal behavior and output structure 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 three sentences long, front-loaded with the primary purpose, and each sentence adds unique value: action, mechanism, and use case/output. No redundant or irrelevant information 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?

Despite lacking an output schema, the description fully explains the return format ('ranked list with score, confidence, signal density per entity'). It also describes the internal process (probing each entity) and constraints (2-8 entities). Annotations cover safety and idempotence. For a tool of this complexity, the description is sufficiently 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 does not add significant meaning beyond what the schema already provides for parameters. The schema for 'entities' already states 'First entry treated as the subject for narrative; rest are competitors,' which is the key semantic detail. No additional insight is given for other 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 states 'Compare AI visibility across multiple entities side-by-side' with a specific verb (compare, probe, rank) and resource (AI visibility scores). It differentiates from sibling ai_visibility_check by explicitly noting it probes each entity and ranks them, making the tool's distinct purpose clear.

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

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

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This implies it should be used for multi-entity comparison rather than single entity checks (which ai_visibility_check handles). However, it does not explicitly state when not to use it or name alternative siblings, though the context is clear.

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

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

The description adds substantial behavioral context beyond annotations: it explains that the tool fans out to two services, handles partial failures gracefully, and warns that bundlephobia's first measurement can take 5-30 seconds. No contradiction with annotations; in fact it complements them.

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

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

The description is somewhat long but is front-loaded with the core purpose and each sentence adds unique value. It could be slightly more structured, but it remains concise given the complexity of the tool behavior.

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

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

Despite no output schema, the description thoroughly details return fields (summary block, advisory detail, links, alternative versions) and handles edge cases like partial failures. This makes the description complete enough for effective tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped package names are accepted and that version defaults to latest, which is not obvious from the schema alone. This extra semantic guidance warrants a score of 4.

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

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

The description clearly defines the tool as a composite check for npm packages using deps.dev and bundlephobia. It specifies the exact purpose: assessing if a package is safe, popular, or small, and distinguishes it from siblings as no other tool covers this specific composite check.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and provides limitations (NPM ecosystem only in v1; other ecosystems fall under deps.dev:version directly). This gives clear guidance on when to use this tool vs alternatives.

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

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

Annotations declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds useful behavioral context by specifying the return structure (name, summary, record_count, owner/org, url) and confirming the search-by-keyword functionality, going beyond the annotations.

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

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

The description is two sentences long, front-loading the purpose and scope in the first sentence and detailing the output and subsequent usage in the second. No unnecessary words.

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

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

Although there is no output schema, the description explicitly lists all return fields, compensating adequately. The schema fully describes parameters. The description also ties into sibling tools (query_layer, layer_info) for onward processing. Context is complete for this search tool.

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

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

All three parameters (limit, query, org_id) are fully described in the schema (100% coverage). The description does not add additional semantic details beyond what the schema provides, so the 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 Cranston GIS open geospatial datasets by keyword, with examples like 'parcels, zoning & city services'. It distinctively mentions returning a URL for use with query_layer/layer_info, differentiating from those sibling tools.

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

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

The description explicitly says to pass the returned URL to query_layer or layer_info, providing clear next-step usage. However, it does not explicitly mention when not to use this tool or specify alternatives for related search tasks among the large sibling list.

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. Description adds valuable technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap, truncation behavior. No contradictions with annotations.

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

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

Description is front-loaded with purpose and usage, uses efficient language with 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?

Explains return type (passages with offsets and scores) and truncation. Lacks some edge cases (e.g., empty query) but overall complete for a search tool given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra semantics beyond what the schema already provides for each parameter.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific verb 'search inside' and resource 'a fetched record'. It distinguishes from siblings by noting it pairs with ask_pipeworx_grounded for grounding over passages.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and how it pairs with a sibling tool. Lacks explicit 'when not to use' but the context is clear enough.

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

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

The description adds significant behavioral context beyond annotations: requirement for OAuth account, type-specific param details, delivery channel constraints (phone verification, 10/day SMS cap, webhook signing and auto-disable). No contradiction with annotations.

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

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

The description is well-structured, front-loading the main purpose and return, then prerequisites, types, and delivery channels. While slightly long, each sentence adds value and there is no redundancy.

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

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

Given the tool's complexity (multiple types, delivery channels, constraints), the description is comprehensive. It covers prerequisites, all types with examples, delivery channels with detailed rules, and the return value, with no missing critical information.

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

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

Even with 100% schema coverage, the description enriches parameters with concrete examples (e.g., sec_8k items:['5.02'] = officer change) and elaborates on delivery options with constraints, adding meaning beyond the schema.

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

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

The description clearly states the tool creates a subscription to a live-data event stream, specifying the verb 'Create' and the resource 'subscription'. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by its action and return of a subscription id.

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

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

The description provides explicit context on when to use (monitoring subscription) and prerequisites (Pipeworx OAuth account). It lists supported types and delivery channels, but does not explicitly exclude scenarios or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds value by detailing the return structure (category-bucketed examples with exact tool+argument shape) and the optional topic focus, but 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 slightly verbose but well-structured, front-loading trigger phrases and then providing details. Every sentence adds value, though minor shortening is possible.

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 optional param, no output schema, comprehensive annotations), the description fully covers purpose, usage, and return format, 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 coverage is 100% with a well-described optional topic parameter. The description enhances meaning by listing example topics and specifying that omitting it gives a full spread.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool and argument shapes. It distinguishes from sibling tools by mentioning meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly advises to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools, providing clear context and alternatives.

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

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

Beyond annotations (destructiveHint=false), the description adds that the row is deactivated, not deleted, so historical events remain available via recent_alerts. It also confirms ownership enforcement, which is a behavioral trait not captured by annotations. No contradictions.

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

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

Two sentences with no wasted words. The main action is front-loaded. Each sentence adds distinct value: action, ownership, and effect on data.

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 one parameter, no output schema, and informative annotations, the description covers all necessary context: what it does, who can use it, and what happens to the record. No gaps for an agent to make incorrect assumptions.

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

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

Schema coverage is 100% for the single parameter 'id', which is already described as 'Subscription id (uuid) returned by subscribe.' The description does not add additional meaning beyond confirming usage by id. Baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement. The action and scope are unambiguous.

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

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

The description explicitly states 'You can only cancel your own subscriptions,' providing a clear usage boundary. It also explains that the row is deactivated, not deleted, implying when it's appropriate to use (own subscriptions) and that historical data is preserved. Alternatives are not named but implied by context.

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

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

The description adds behavioral context beyond annotations: it specifies data sources (SEC EDGAR + XBRL), output types (verdicts, structure, citation, delta), and scope (v1 supports company-financial claims). Annotations already indicate read-only, idempotent, non-destructive behavior.

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

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

The description is concise (5 sentences) yet packed with key information: usage patterns, domain, data sources, output summary, and efficiency benefits. Each sentence adds essential detail 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 adequately explains return values (verdicts, structured form, citation, percent delta). Given the tool's simplicity (1 parameter, no nested objects) and rich annotations, the description is complete enough for an agent to invoke correctly.

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

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

The single parameter 'claim' has clear description in both schema and tool description. Schema coverage is 100%, and the description provides natural-language examples and format guidance, adding value beyond the schema's description.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources, with specific examples and domain (company-financial claims for US public companies). It distinguishes from siblings by focusing on claim verification rather than general research or entity resolution.

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 ('whenever the agent needs to check whether something a user said is factually correct') and explains benefits over alternatives (replaces 4-6 sequential calls). It does not explicitly state when not to use, but the domain limitation is implied.

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