Arcgis Aurora

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

Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds transparency about key handling (API key passed through), cost (free default, pay Anthropic directly), and return structure. 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 (4 sentences, ~100 words) and front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description details the return structure (per-model {score, confidence, signals, raw_response} + combined view) and covers all parameters. Use cases and key handling are fully explained.

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 clarifying the default model and the role of _apiKey for Anthropic, which goes beyond schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility. It specifies the verb 'probe', the resource 'LLMs', and the output 'score (0-100)'. The purpose is distinct from siblings like 'entity_profile' and 'scan_competitor_ai_presence'.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model and optional Anthropic with BYO key. However, it does not explicitly state when not to use the tool or suggest alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world. The description adds context about routing to 4,552 tools, filling arguments, returning structured answers with citation URIs, enhancing transparency beyond annotations.

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

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

The description is somewhat lengthy but front-loaded with key guidance and examples. 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 tool complexity (multiple aliases, many sources), the description covers usage, alternatives, and behavior well. No output schema needed since tool returns structured answers with citations.

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

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

Schema coverage is 100%, so the description adds little beyond listing aliases for 'question'. Baseline 3 is appropriate as the schema already documents the parameter adequately.

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: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists specific domains like SEC filings, FDA drug data, etc. It distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly tells when to use this tool vs alternatives with phrases like 'PREFER OVER WEB SEARCH' and 'Step up only when needed:' for ask_pipeworx_grounded and deep_research. Provides concrete query examples and trigger words.

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, open-world, idempotent, non-destructive. Description adds crucial details: return structure with {answer, evidence, confidence, source, fetched_at, refusal_reason:null} on success, and explicit refusal reasons. Also mentions extra LLM call cost.

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

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

Description is well-structured and front-loaded, but could be slightly more concise. Every sentence adds value, though some redundancy exists (e.g., listing aliases in description beyond schema).

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 specifies the return format, including success and refusal cases. Given the tool's complexity (routing, extraction, refusal handling), the description provides complete contextual information.

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

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

Schema description coverage is 100%, with 'question' and 5 aliases all described. The description does not add new semantic meaning beyond what the schema provides. 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 'Hallucination-resistant answer mode for high-stakes reads' and explains the core function: it routes to the right tool, fetches data, and extracts answer only from tool result. It distinguishes from sibling ask_pipeworx by specifying the extraction step and usage context.

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

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

Explicitly tells when to use: for high-stakes reads where answers will be quoted/cited/acted on, and when not to: prefer ask_pipeworx for casual lookups due to extra cost. Provides concrete examples (financial verdicts, legal claims, etc.).

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 provides extensive behavioral details beyond annotations: market resolution, classification, fan-out logic, response shapes, resolver contract, parent event extractor, news fallback mechanisms, safety short-circuits, and cancellation rule parsing. Annotations indicate readOnly, openWorld, idempotent, non-destructive, which align perfectly with the described 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 long but every sentence is information-dense and earns its place. It is front-loaded with the core purpose and then details sub-components. Minor room for tightening, but overall well-structured for the complexity.

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

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

Given the tool's complexity (research with multiple sub-features, safety checks, edge cases), the description is remarkably complete. It covers resolution confidence, parent events, news fallback, illiquid markets, cancellation rules, and blocking mechanisms. No output schema exists, so the description compensates fully.

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

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

Schema coverage is 100% and the description adds significant meaning: it explains what each parameter accepts (e.g., market can be slug, URL, or question text; depth enum values; include_raw purpose). Examples are provided for market input, aiding understanding.

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

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

The description clearly states the verb 'Research', the resource 'Polymarket bet', and the action 'pulling the relevant Pipeworx data'. It specifies the input types (slug, URL, question text) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on comprehensive research.

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

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

Explicit usage scenarios are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This clearly guides when to invoke the tool. However, it does not explicitly state when NOT to use it or directly reference alternatives among siblings, though siblings are listed elsewhere.

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. Description adds specifics: data sources (SEC EDGAR/XBRL, FAERS), sorting behavior, citation URIs, and that it replaces 8-15 sequential lookups. 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 a single dense paragraph but front-loaded with usage examples. Could be slightly more structured but 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?

No output schema, but description sufficiently explains return (paired data + citation URIs). Sibling tools like entity_profile suggest single entity queries, so comparison use case is well-covered.

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. Description adds detail on what data is pulled per type (e.g., 'LATEST 10-K revenue' for companies) and constraints like '2-5 tickers'. Enhances schema understanding.

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

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

The description clearly states the tool provides side-by-side comparison of 2-5 companies or drugs with specific examples like 'compare X and Y' and 'rank these companies'. It distinguishes from 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides contextual examples of when to use ('which is bigger', 'head to head').

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?

Amplifies on annotations (readOnlyHint, openWorldHint, etc.) by detailing parallel decomposition, return format ('findings packet: verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation per finding, with explicit gaps[]'), expected 15-60s wait, and account tiers. No contradiction with annotations.

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

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

Description is lengthy but front-loaded with critical account requirement and alternative tool. Every sentence serves a purpose: specifying data sources, process, return type, and use cases. Could be slightly tighter but remains efficient.

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

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

Given tool complexity, 2 parameters, no output schema, and 30+ siblings, this description covers all key aspects: authentication, data sources, parallel processing, output format, gaps handling, timing, and clear differentiation from alternatives. No missing critical info.

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

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

Both parameters (question, depth) have clear descriptions in schema (100% coverage). Description adds concrete meaning: depth enum values map to facet counts (quick=3, standard=5, thorough=8) and question accepts natural language broad queries. This enhances schema info.

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

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

Description clearly states it performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and contrasts with open-web search. It uses specific verbs ('decomposes', 'routes', 'returns') and distinguishes from sibling ask_pipeworx by scope and data source type.

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 'for broad/multi-part questions over structured data' and provides alternatives: use ask_pipeworx for single lookups or breaking news. Also states account requirement and when deep_research returns empty gaps, guiding appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds key behavioral traits: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes that results are 'ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is front-loaded with the core purpose, followed by a list of example data domains, and ends with usage guidance. Every sentence adds value without redundancy. Length is appropriate for the complexity.

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

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

Despite having no output schema, the description fully specifies what the tool returns (top-N tools with schemas and examples). It covers all required aspects: purpose, behavior, parameters, and return format, fitting the tool's role as a discovery utility among many 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% (baseline 3). The description adds value by explicitly listing all aliases (q, task, search, description) as aliases for the main 'query' parameter, clarifying that they are interchangeable. This reduces confusion for the agent, justifying 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 uses a specific verb 'Find' and resource 'tools', enumerates numerous example queries (SEC filings, FDA drugs, etc.), and clearly distinguishes from sibling tools by positioning itself as a discovery tool. This leaves no ambiguity about what the tool does.

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

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

Explicit guidance is provided: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies it's not for direct task execution. No exclusions needed.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. Description adds behavioral context: soft-fails on patents due to API sunset, returns specific data (cik, filings with URIs, fundamentals), and confirms it's a parallel call. No contradictions.

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

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

The description is front-loaded with examples and a clear imperative. Though lengthy, every sentence adds value. Could be slightly tightened, but structure is logical.

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

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

Given complexity (multiple data sources, multiple return fields), the description thoroughly covers return values (cik, filings, fundamentals, patents, news, LEI) and their status (patents soft-fail). No output schema exists, so description compensates well.

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%, documenting type and value parameters. Description adds meaning by explaining usage (ticker or CIK, names not supported) and providing examples, beyond the schema's enum and type definitions.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company. It uses specific verbs like 'profile' and lists example queries ('Tell me about X', 'research Acme'), distinguishes from siblings like resolve_entity (mentioned for name resolution) and compare_entities.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also indicates when not to use (if only a name, use resolve_entity first). Provides clear context for tool selection.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description repeats 'delete' but adds no new behavioral context like irreversibility or side effects. Adequate but minimal added value.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly efficient.

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

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

Simple tool with one parameter and no output schema. Description explains what it does and when to use it. Completely adequate for the tool's complexity.

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

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

Schema coverage is 100% with a clear description 'Memory key to delete'. The description says 'by key' but adds no new meaning beyond the schema. Baseline 3 appropriate.

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

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

The description clearly states the action 'delete' and the resource 'memory by key', and distinguishes from siblings 'remember' and 'recall' by pairing with them.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with related tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds detailed process (fetches, extracts title/description/links, emits markdown) and output context, fully aligning with and enriching 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 concise and front-loaded with the main action, followed by process and use cases. Every sentence is meaningful, though slightly verbose in listing use cases.

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

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

Given no output schema, the description adequately describes the output (single text blob) and process. It covers purpose, structure, and use cases, though it could mention limitations or error 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%, but the description adds value by specifying default and max for max_links (25, max 50) and clarifying url format. This goes beyond schema.

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

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

The description clearly states it generates an llms.txt file for any URL, specifies the output format, and lists three explicit use cases. It distinguishes itself from sibling tools by focusing on this specific task.

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 (client indexing, personal drafts, competitor auditing) but does not mention when not to use it or compare to alternatives like ai_visibility_check.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specific return values but does not disclose any additional behavioral traits beyond what annotations cover.

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

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

Single concise sentence (25 words) front-loaded with purpose. No filler, each part earns its place.

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

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

Given no output schema, description covers all returned items (fields, geometry, count, capabilities). Could mention response format (e.g., JSON) but not essential. Overall complete for a simple schema-retrieval tool.

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

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

Schema coverage is 100% with a clear URL parameter description. The tool description adds no additional parameter semantics beyond the schema's own description. 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?

Description clearly states it retrieves schema of an ArcGIS Feature/Map Service layer, listing specific data items: fields, geometry type, record count, capabilities. This distinguishes it from sibling 'query_layer' which queries data.

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

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

No explicit guidance on when to use vs alternatives. The description implies usage by stating 'by url', but lacks when-not or sibling differentiation like 'use query_layer for data queries'.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return fields and default behavior (active only). 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 concise sentences, front-loaded with purpose, 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 low complexity, annotations, and schema covering the parameter, the description sufficiently covers return fields and usage context. No output schema, but fields listed.

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

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

Single parameter is fully described in schema (100% coverage). Description does not add extra meaning beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates return fields. Differentiates from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Implies usage context, though not exhaustive.

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

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

The description discloses rate limits (5 per identifier per day) and that it's free with no quota impact. Annotations indicate it's not read-only but not destructive, which aligns with sending feedback. 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, well-structured, and front-loaded. Every sentence adds value: purpose, use cases, formatting guidance, rate limits. No unnecessary words.

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

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

Given the tool's simplicity and lack of output schema, the description is complete. It covers what the tool does, when to use it, how to use parameters, and constraints like rate limits. 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% and the description adds meaning beyond the schema by explaining when to use each type, what to include in message (be specific, 1-2 sentences), and the optional context 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 the tool's purpose: to give feedback (bug, feature, praise) to the Pipeworx team. It uses specific verbs and distinguishes itself from sibling tools by being the feedback channel.

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

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

The description explicitly tells when to use each feedback type (bug for wrong data, feature/data_gap for missing tools, praise for good experiences) and provides guidance on how to frame the feedback (describe in terms of tools/packs, avoid end-user prompt).

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

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

Beyond annotations (readOnly, idempotent), the description adds key details: data source (CF analytics-engine), no PII, and cache duration per window. No contradictions.

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

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

Front-loaded with the core purpose, followed by bullet-style use cases and a concise note on caching. Every sentence adds value with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers inputs, outputs (top tools/packs/volume), and caching. Could optionally specify the exact return structure.

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 'window' is fully covered by the schema description (enum and purpose). The description does not add substantial new meaning beyond what the schema already provides.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) over configurable windows. It distinguishes itself from sibling tools by focusing on aggregated popularity signals.

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

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

Three concrete use cases are provided, and caching behavior is mentioned. However, it does not explicitly exclude use cases or compare to alternatives like 'discover_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?

Disclosures go well beyond annotations (readOnlyHint, idempotentHint). Details how each mode processes inputs (walks child markets, checks monotonicity, computes partition_check), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check (theoretical vs realizable edge). No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the core purpose, but it is verbose due to the complexity of the tool. Every sentence adds value, yet an AI agent might benefit from slight trimming. 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?

Covers the response structure (opportunities[], partition_check fields) and fill check, but lacks explicit enumeration of all return fields in a structured format. Given the absence of an output schema, it provides sufficient context for agent understanding, though minor details (e.g., error handling) are omitted.

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

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

Adds extensive meaning beyond the input schema's brief descriptions. Explains how 'event' and 'topic' parameters drive distinct analysis paths, including response structure and fill check logic. Schema coverage is 100%, but the description provides critical operational context not captured in 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools (e.g., polymarket_edges) by focusing specifically on 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?

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan,' 'event (recommended for a specific market),' and 'topic for cross-event scanning.' Also directs users to polymarket_fill_risk for custom sizing, offering clear alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive behavioral context: five model families, caching at 1h, diagnostics for empty segments, and per-opportunity fields like edge_pp_net, kelly_fraction, and 24h-move warnings. No contradictions with annotations.

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

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

The description is very detailed (376 words) but lacks conciseness. It front-loads the core purpose but then dives into extensive details about model families, segments, and diagnostics that could be summarized. While informative, it is not optimally concise for quick agent parsing.

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 9 parameters, no output schema, and complex behavior, the description is extremely thorough: it covers all three response segments, diagnostics, caching behavior, tradeable-edge knobs, and per-opportunity fields. An agent has enough information to effectively use the tool.

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

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

Schema coverage is 100% (all 9 parameters documented). The description adds value beyond schema by explaining why min_kelly does not filter partition arbs (for min_partition_leg_kelly) and providing usage tips like 'Bump for very thin partitions' for slippage_pp. Baseline 3, plus extra context justifies a 4.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly designed for 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage by emphasizing edge-finding across model families.

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

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

The description provides a clear use case ('what should I bet on today') and discusses knobs for filtering (min_liquidity, max_spread_pp, etc.), guiding when to use tradeable-edge filters. However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations indicate read-only, open-world, idempotent. Description extends with: history depth bounded by 60-day TTL, snapshots on cache-miss, gaps mean no scan, decay from daily closes (not intraday). 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?

Long but well-structured; front-loaded with purpose, then argument details, limits. Every sentence adds value; could tighten slightly.

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

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

Despite no output schema, description fully explains return structure (tracked[], expired[], snapshot_dates[]), including fields like first_seen, trend, decay_pp_per_day, lifespan_days. Covers limitations and gaps comprehensively.

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

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

Schema covers 100% with descriptions. Description adds: default values (days=14, window='1wk'), clamp (2-30), and explains that 'window' refers to snapshot family. 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers specific questions about edge longevity and decay, distinguishing it from sibling tools like polymarket_edges (raw edge data). Uses precise verbs ('Answers', 'tracked', 'expired') and resource scope.

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 context: when to use (to know edge age/decay), what data is returned, and limitations (TTL, snapshot gaps). Does not explicitly exclude alternatives, but strong context implies sibling polymarket_edges is for raw data.

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 openWorldHint, so the bar is high. The description adds significant context: it 'walks the ladder,' returns specific fields like slippage_pp and verdict, and warns about 'forced_directional_risk.' This enriches the behavioral model 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 dense but well-organized, using all-caps keywords and bullet-like structure for modes and warnings. Every sentence adds necessary context, though it is relatively long. It front-loads the core purpose effectively.

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

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

Given the tool has 4 parameters, no required, 100% schema coverage, and no output schema, the description provides extensive coverage: it lists return fields for both modes, explains the verdict values, and details the basket mode's thin_legs and forced_directional_risk. This is comprehensive enough for an agent to understand usage and outcomes.

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 beyond schema by explaining the auto logic for 'side' in basket mode (default from partition sum) and clarifying how 'size_usd' is interpreted in basket mode as 'settlement notional S (shares per leg).' This compensation justifies a 4.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making its unique role evident.

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

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

The description provides explicit when-to-use guidance: 'REQUIRES one of market or event' and 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it (theoretical overround not capturable, partial fills convert arb to unhedged position), setting clear boundaries.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds extensive behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and warnings about non-equivalent bet shapes. No contradictions with annotations.

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

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

The description is relatively long but well-structured with sections (modes, response, safety fields). Every sentence adds value, though it could be slightly more concise. The structure aids readability.

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

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

Given the complexity (3 optional parameters, no output schema), the description is thorough. It covers all necessary aspects: modes, parameter interactions, response fields, safety checks, and temporal alignment. Without an output schema, this level of detail is essential for the agent.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining the topic list, override behavior, and providing examples. It clarifies how parameters interact and what each mode does beyond the schema.

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

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

The description clearly states it's a cross-venue spread tool comparing Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and contrasts with sibling tools like polymarket_arbitrage by focusing on inter-venue differences.

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

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

The description explains when to use the tool (to compare prices across venues) and provides cautionary notes (most pre-mapped topics return compatibility_warning). It could be more explicit about alternatives, but the context hints at limitations.

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, such as returning attribute rows and geometry. Annotations already indicate read-only and non-destructive behavior, so the description complements this without contradiction.

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

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

The description is a single, front-loaded paragraph of three sentences. Each sentence serves a purpose: defining the action, listing key parameters, and giving an example. 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?

The description covers return type and key parameters. Given no output schema, it mentions geometry and attributes. It could be improved by explicitly mentioning default limit and pagination behavior, but overall it's adequate.

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

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

With 100% schema coverage, baseline is 3. The description adds value by providing examples (e.g., 'STATE = 'CA'', limit 1-2000) and specifying URL format must end in /FeatureServer/<n> or /MapServer/<n>, which is not in 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 queries an ArcGIS Feature/Map Service layer by URL, using SQL-like parameters. It distinguishes itself from sibling tools like layer_info which likely provide metadata, making the purpose specific and unambiguous.

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

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

The description provides context by mentioning the URL comes from search_datasets and gives example usage ('where="1=1" + out_fields="*" to sample'). However, it does not explicitly state when not to use this tool vs alternatives like layer_info.

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

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

Adds significant value beyond annotations: describes listing behavior when key omitted, scoping to identifier, and pairing with save/delete. Annotations declare readOnlyHint=true, destructiveHint=false, which is consistent. No contradictions.

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

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

Three sentences, each earning its place: first states core function, second provides usage context, third adds scoping and related tools. No waste, front-loaded with the main action.

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

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

For a simple read tool with one optional parameter and annotations covering safety, the description fully covers retrieval behavior, listing behavior, scoping, and links to related tools. No output schema needed as return is simple value or list.

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

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

Schema coverage is 100% with a clear description for the optional 'key' parameter. The description repeats that omitting key lists all keys, which adds no new information. Baseline of 3 is appropriate as schema already explains parameter behavior fully.

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 keys if no key argument is provided. It uses specific verbs ('retrieve', 'list') and resources (saved values/keys), and distinguishes from siblings like remember and forget by mentioning them in context.

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

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

Explicitly states when to use ('look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember/forget. Lacks explicit 'when not to use' but the context is clear enough given the sibling tools are diverse and distinct.

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 contradicts annotations: annotations claim readOnlyHint=true but description states mark_read:true flags events as read, which is a state modification. This is a direct 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?

Four sentences, each adding value. Front-loaded with purpose, no fluff, efficient.

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

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

Describes return format, filtering, mark_read behavior, polling, and alternative API. Covers all aspects for effective use despite no output schema.

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

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

Adds examples for type and since, and explains the effect of mark_read on subsequent calls. With 100% schema coverage, baseline is 3; the added context raises it to 4.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts with specific attributes. It distinguishes from siblings like list_subscriptions which lists subscriptions, not alerts.

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

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

Provides filtering guidance with type and since, explains mark_read behavior for polling, and mentions an alternative HTTP endpoint. Lacks explicit when-not-to-use but gives 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 comprehensively discloses behavior: fans out to SEC EDGAR, GDELT/GNews (with fallback logic), and USPTO (with soft-fail note). It mentions the return format (changes[] grouped by source, total_changes, pipeworx:// URIs). Annotations already indicate readOnly, idempotent, non-destructive, so the description adds valuable context beyond that without contradiction.

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

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

The description is relatively long but front-loaded with example queries, which makes the purpose immediately clear. Every sentence adds distinct information (sources, fallback, return structure, sibling reference). Slight redundancy ('GDELT→GNews fallback' appears twice) prevents a perfect score, but it remains efficient.

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

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

For a tool that queries multiple external sources and returns aggregated results, the description is remarkably complete. It explains all three input parameters, the data sources queried, fallback behavior, and the structure of the output (changes grouped by source, total_changes, citation URIs). No output schema exists, so the description must cover what is returned, which it does thoroughly.

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 the baseline is 3. The description adds value by documenting the accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and providing example values for 'value' (ticker or CIK). It also recommends '30d' or '1m' for typical monitoring, which helps agents choose defaults.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, listing specific example questions (e.g., 'What's new with X', 'latest on Y') and explicitly distinguishes from the sibling 'entity_profile' tool, which is for static profiles. The verb 'change feed' and resource 'company' are specific.

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

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

The description gives explicit guidance to use 'entity_profile' instead for static profiles, and it illustrates typical use cases (e.g., 'news on Tesla recently'). However, it could be more explicit about when not to use it (e.g., if only a single source is needed) or about prerequisites (e.g., company must have a ticker/CIK). The fallback behavior (GDELT→GNews) is mentioned, which aids decision-making.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; description adds context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' 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 compact with three sentences: purpose, usage guideline, and behavioral details. Every sentence adds value, no redundancy, and the most important information is front-loaded.

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

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

Given the tool has 2 fully described parameters, no output schema needed (it's a write operation), and annotations cover safety, the description provides all necessary context: persistence, scoping, and pairing with sibling tools.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples like 'subject_property', 'target_ticker' for keys and 'findings, addresses' for values, providing additional meaning beyond the schema's basic 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 'Save data the agent will need to reuse later' with a specific verb and resource, and distinguishes from sibling tools like 'recall' and 'forget' by mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

Explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again.' and provides context on when not to use alternatives by referencing 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context that it 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups,' which goes 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 front-loaded with examples and a clear usage guideline, and each sentence adds value. It is slightly detailed but well-structured, without 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?

Without an output schema, the description comprehensively covers both entity types, their return fields including citation URIs, and acceptable inputs. It fully compensates for the lack of an output schema and handles complexity well.

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 significantly enriches parameter meaning by detailing what each type returns (e.g., for company: ticker, CIK, company_name, and citation URI) and acceptable input formats, adding value beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers with specific verbs like 'resolve' and examples ('ticker', 'CIK', 'RxCUI'). However, it does not explicitly differentiate from sibling tools like 'entity_profile' or 'compare_entities', which could overlap in 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 'Use FIRST whenever you have a name but need an ID,' providing clear context. It also lists supported entity types with input/output specifics, but does not explicitly state when not to use or give alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds that it probes each entity with ai_visibility_check and returns a ranked list, which is consistent with annotations. No extra behavioral traits beyond annotations are disclosed, so the description adds moderate value.

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

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

The description is three sentences with no waste: first sentence states purpose, second describes process, third gives a use case. It is front-loaded and every sentence provides essential information.

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

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

The description explains the output (ranked list with score, confidence, signal density) and the probing mechanism. Given no output schema, this covers return values. It does not address error handling or prerequisites, but for a moderate-complexity tool with good annotations, it 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 coverage is 100% with descriptions for all parameters. The description adds value by explaining the roles of parameters: entities (first is subject), models (default workers-ai), _apiKey (required if anthropic), and context (disambiguates). This semantic context goes beyond the schema's descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the verb 'compare' and specifying the resource as 'AI visibility'. It distinguishes itself from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It implies when to use this tool but does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entities.

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

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

The description adds significant behavioral context beyond the annotations (readOnly, openWorld, idempotent): it describes partial failure degradation, potential latency for new versions (5-30s), and the sources_failed field, which helps the agent handle timeouts gracefully.

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

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

The description is a single paragraph but well-structured and concise: it front-loads the core purpose, then covers data sources, usage guidance, limitations, and failure behavior. Every sentence adds value with no filler.

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

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

Given the tool's complexity (combining two external services) and the absence of an output schema, the description provides a good overview of return fields (is_latest, license, bundle sizes, etc.) and failure handling. Minor gap: the return structure of advisory details and links could be more explicit, but it's sufficient for most use cases.

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

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

The schema already describes both parameters (package and version) with 100% coverage, so baseline is 3. The description adds extra context: scoped packages (@types/node) are accepted, and version defaults to latest when omitted, which aids correct invocation.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages including safety, popularity, and size metrics. It distinguishes from sibling tools by specifying the npm ecosystem focus and the combination of deps.dev and bundlephobia data.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small"', and clarifies that for other ecosystems (PyPI, Maven, etc.) one should use deps.dev directly, which helps the agent decide 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 read-only, idempotent, and open-world behavior. The description adds context on the specific return fields and the downstream workflow, enhancing transparency beyond annotations.

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

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

The description is two sentences long, front-loads the purpose, and provides essential output details. Every sentence adds value without redundancy.

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

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

For a tool with three parameters, no output schema, and full annotations, the description adequately covers what the tool returns and how to use the results. Minor gaps like sorting or pagination are 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 description coverage is 100% and each parameter is well described in the schema. The tool description does not add further meaning to parameters, which is acceptable given the schema's completeness.

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 open geospatial datasets by keyword and lists specific return fields (name, summary, record_count, owner/org, Feature Service url). It also references sibling tools for downstream use, distinguishing its role as a discovery 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 explains what the tool does and explicitly instructs to pass the returned url to query_layer or layer_info, implying when to use those alternatives. However, it does not give explicit when-not or exclusions for using search_datasets versus other 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 significant behavioral details beyond annotations: it mentions BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation flag, and that passages include character offsets and similarity scores. Annotations already indicate read-only, idempotent, and non-destructive, which are consistent.

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

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

The description is six sentences, all front-loaded with the purpose in the first sentence. Every sentence adds value (usage guidance, pairing, technical details, limits), with no redundant or 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?

Without an output schema, the description fully explains what is returned: 'top-N passages with character offsets and similarity scores'. It also covers input constraints (200K cap, truncation flag) and the embedding technique. No gaps are apparent.

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

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

The input schema has 100% description coverage, so baseline is 3. The description adds some context (e.g., natural-language query examples, truncation flag for text) but does not significantly enhance understanding beyond the schema definitions.

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

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

The description clearly states it performs semantic search inside a fetched record. It uses specific verbs and resource: 'semantic search INSIDE a fetched record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with cramming the whole record into a prompt.

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

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

The description explicitly tells when to use: 'Use when the record is too big to cram into the prompt'. It also describes the alternative pairing with ask_pipeworx_grounded and gives concrete examples like SEC 10-K and articles, making usage context 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 discloses behavioral traits beyond annotations: returns subscription ID, requires OAuth account, SMS cap of 10/day, webhook signing and secret returned once, auto-disable after 10 failed webhook runs. Annotations indicate idempotentHint=true (consistent with creation), and no contradictions.

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

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

The description is a single paragraph that is front-loaded with purpose. It is fairly long but every sentence adds value. Could be slightly more structured with bullets, but remains clear and efficient.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is thorough. It covers type-specific params, delivery details, account requirements, and notes that the subscription ID is returned. It addresses all essential aspects for correct invocation.

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

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

Despite 100% schema coverage, the description adds significant meaning: for type and params, it provides example values and conditional requirements (e.g., sponsor or condition for clinical_trial). For delivery, it explains webhook signing, SMS verification, and caps. This greatly aids parameter understanding.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes from siblings like list_subscriptions (listing) and unsubscribe (removal) by focusing on creation and providing specific supported types with examples.

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 specifies the requirement of a Pipeworx OAuth account (not anonymous/BYO), lists supported types, parameters, and delivery channels. While it doesn't explicitly state when not to use, it provides enough context to decide when to use this tool vs alternatives like recent_alerts for immediate data pulling.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context about the output format (category-bucketed example questions with tool + argument shapes) and behavior with/without the topic parameter, which is valuable 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 front-loaded with key phrases and uses a single paragraph. While it includes many example questions and categories, it remains focused and each sentence adds value. It could be slightly more concise but is still well-structured.

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

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

Given no output schema, the description adequately describes the output (category-bucketed example questions with tool and argument shape) and the tool's role as an onboarding guide. It covers when to call, how to customize, and what to expect, making it complete for an agent.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the effect of omitting vs. providing the topic parameter and giving concrete examples of topic values (e.g., 'finance', 'pharma'). This enriches 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 as an onboarding entry point that returns example questions categorized by topic. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself from sibling tools by being the first tool to use when unsure of Pipeworx's capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and instructs when to pass the optional topic parameter or omit it for a full spread. It also mentions learning how to call meta-tools, providing clear usage context.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds that the row is deactivated (not deleted) and historical events remain, which goes beyond annotations. 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?

Two sentences, front-loaded with the action, no unnecessary words. Every sentence adds value.

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

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

For a single-parameter tool with no output schema and informative annotations, the description covers all necessary context including ownership and effect on data.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description does not add further meaning beyond what the schema provides, meeting the 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 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

The description includes ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear context for when to use the tool. It lacks explicit when-not-to-use or alternatives but is still strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: specifies data source (SEC EDGAR + XBRL), lists possible verdicts, mentions extracted structured form, actual value with citation, and percent delta. No contradiction with annotations.

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

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

Description is slightly lengthy but well-organized: starts with example triggers, then purpose, scope, return details, and value proposition. Every sentence contributes useful information, and the structure is logical.

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

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

Given there is no output schema, the description effectively explains return values (verdict types, citation, delta) and data source. It provides enough detail for an agent to understand what the tool does and what to expect, without being overly verbose.

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

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

Only one parameter 'claim' with schema description providing examples. Schema coverage is 100%, so baseline is 3. The description adds meaningful context about supported claim types (company-financial, public US companies) and format examples, which aids correct parameter construction.

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 concrete example queries, specifies the domain (company-financial claims for public US companies), and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes itself from general fact-checking by narrowing the scope.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' Also mentions it replaces multiple sequential calls, implying efficiency. While it doesn't explicitly mention when not to use it or compare with siblings, the domain specificity provides clear boundaries.

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