Arcgis Sanbernardino

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive nature. Description adds context: probing multiple LLMs, scoring 0-100, return structure, and the fact that Anthropic calls require a BYO key with direct payment to Anthropic. Could mention potential latency or rate limits.

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 with no fluff. Front-loaded with action and outcome. Every sentence adds 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?

Despite no output schema, description explains return format: per-model {score, confidence, signals, raw_response} and a combined view. Covers models, optional parameters, and usage scenarios completely.

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

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

Schema has 100% description coverage. Description adds meaning: explains `_apiKey` as 'BYO key — you pay Anthropic directly', `context` as 'helps disambiguate common names', and clarifies default model behavior. Adds significant value beyond the schema.

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

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

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are specific, and the scope is well-defined, distinguishing it from siblings like 'entity_profile' and 'scan_competitor_ai_presence' which focus on different aspects.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also notes the default model and optional Anthropic key. However, it does not explicitly exclude scenarios where alternatives like 'entity_profile' might be more appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it routes to many sources, fills arguments, and returns stable citation URIs, which is useful context beyond annotations.

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

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

The description is long but well-structured: clear purpose first, then usage guidance, examples, and sibling comparisons. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one required param, no output schema), the description fully covers behavior, return value (structured answer with citations), and tier compatibility. No gaps.

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

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

Schema coverage is 100% with all aliases documented. The description adds little beyond saying 'natural language question', so it meets but does not exceed the baseline for high-coverage schemas.

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

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

The description explicitly states that the tool routes factual questions across 4,552 tools and returns structured answers with citations. It clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to upgrade.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for many domains, provides example queries, and gives detailed guidance on when to use alternatives for hallucination-resistance or broad multi-part questions.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: hallucination resistance, extraction from tool result only, explicit refusal reasons ('not_in_source', 'no_tool_match', etc.). 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 front-loaded with the key purpose and is relatively concise for the amount of detail. Each sentence adds value, though it could be slightly tightened without losing information.

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

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

Despite no output schema, the description fully details the return structure on success and failure. It covers cost, routing, extraction methodology, and explicit refusal reasons, making it self-contained for agent understanding.

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

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

Schema coverage is 100% with 6 parameters all aliases for 'question'. Description explains that all aliases are accepted and the parameter is a natural language question, adding clarity 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 states a specific verb ('Extracts answer') and resource ('tool result'), distinguishes from sibling 'ask_pipeworx' by noting it is hallucination-resistant and costs one extra LLM call. It clearly defines the distinct functionality.

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 ('high-stakes reads, quoted/cited information, must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). Provides concrete examples like financial verdicts, legal claims, medical lookups, public statements.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description goes far beyond by detailing error handling (low-confidence short-circuit, closed market detection), tradeability warnings, resolution-rule risk, and response shapes. It also explains the resolver contract and parent event extractor. No contradiction with annotations.

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

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

The description is very long (multiple paragraphs) with extensive detail. It is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), which aids readability. However, it could be more concise; some repetitions and overly verbose explanations weigh it down.

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 (classifiers, fan-outs, edge cases, response shapes), the description is exceptionally complete. It covers low-confidence matches, closed markets, wide spreads, resolution rules, and nested fields. Without an output schema, the description fully compensates by detailing 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?

Schema coverage is 100% with descriptions. The description adds significant value by explaining how 'market' can be a slug, URL, or question text; clarifying 'depth' enum values ('quick' vs 'thorough'); and detailing 'include_raw' default behavior and impact. This enriches the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the outcome (evidence packet + comparison). While it doesn't explicitly distinguish from siblings like 'polymarket_edges', the detailed purpose and output description set it apart.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples for different bet types (BTC, Fed, Hormuz, etc.) and response shapes. However, it lacks explicit 'when not to use' guidance or comparisons with sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: results are sorted by primary metric, data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and inclusion of citation URIs. This goes beyond annotations without contradiction.

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

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

The description is moderately sized but highly efficient. It front-loads example queries and usage guidance, then provides data source details. Every sentence adds value, though slight trimming could improve conciseness. Still very 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 the tool's modest complexity (2 parameters, no output schema), the description covers purpose, usage, data sources, sorting behavior, and output format (paired data + citation URIs). It is sufficiently complete for an agent to understand and invoke the tool correctly, though it could mention edge cases like error handling.

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

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

Input schema has 100% coverage, but the description adds significant meaning: it explains what each type returns (financial metrics for companies, adverse event and trial data for drugs) and provides examples for the values parameter with tickers and drug names. This enriches understanding beyond the schema alone.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes example queries ('Compare X and Y', 'which is bigger') and explicitly distinguishes itself from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description provides explicit guidance to prefer this tool over sequential single-entity lookups when comparing entities, stating it 'ALWAYS PREFER' and 'replaces 8–15 sequential lookups'. It also lists example queries that indicate appropriate use cases, giving clear context for when 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?

Discloses behavioral traits beyond annotations: returns findings packet with verbatim evidence, confidence, source, citations, and explicit gaps. Notes expected duration (15-60s), decomposition and parallel routing. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false.

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

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

The description is long but well-structured: prerequisites first, then purpose, then when to use alternatives, then details. Every sentence adds value, though could be slightly more concise.

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

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

Given the complexity (1160 sources, 4552 tools, 30+ siblings), the description is complete: covers prerequisites, use cases, limitations, output format, and timing. No output schema but described sufficiently.

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

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

Schema coverage is 100% with good descriptions. The description adds context: depth default is 5, broad questions are fine, and explains enum values. This adds 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 it performs grounded multi-source research across 1160 structured data sources, decomposing questions into facets and routing to 4552 tools in parallel. It distinguishes from siblings like ask_pipeworx (single lookup) and bet_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 (broad/multi-part questions over structured data) and when not to (single lookup → ask_pipeworx; breaking/news → ask_pipeworx). Also notes account requirements and alternatives for non-signed-in users.

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 confirm read-only, idempotent, non-destructive behavior. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is valuable context beyond annotations.

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

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

The description is efficiently written with a clear front-loaded purpose. The list of domains is a bit lengthy but every sentence adds value; only minor trimming could be done.

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

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

Despite no output schema, the description thoroughly explains what is returned (top-N tools with names, descriptions, and schemas) and that results are callable. This fully informs the agent about the tool's behavior.

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

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

Schema coverage is 100% and schema already describes each parameter. The description adds value by explaining that 'query' accepts natural language and listing aliases (task, q, description, search), which aids 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 explicitly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.), clearly distinguishing the tool's purpose from siblings. The phrase 'Call this FIRST' differentiates it from other discovery tools.

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

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

The description tells when to use ('when you need to browse, search, look up, or discover what tools exist') and emphasizes calling it first. It doesn't explicitly state when not to use, but the guidance is clear and practical.

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 mark it as read-only, idempotent, and non-destructive. Description adds critical details: fans out across multiple sources, mentions USPTO sunset with soft-fail, documents news fallback (GDELT→GNews), and confirms parallel execution. 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 dense with examples and details, front-loading with common queries. Could be slightly more streamlined, but every sentence contributes actionable information.

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

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

Given no output schema, description thoroughly enumerates all return fields (CIK, filings with URIs, fundamentals sorted, patents status, news fallback, LEI). Covers limitations and fallbacks, making it complete for an agent's decision.

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

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

Input schema covers both parameters with clear descriptions. Tool description enhances with usage hints (zero-padded CIK, ticker examples) and reaffirms name restriction. Adds value beyond schema, but schema already good.

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

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

Description specifies the tool returns a holistic cross-source profile for US public companies, listing exact data points (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from sibling tools like resolve_entity by explicitly stating when to use each.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and 'names not supported (use resolve_entity first)'. Provides clear when-to-use and when-not-to-use guidance along with 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 destructiveHint=true, but the description adds behavioral context by specifying that it clears sensitive data. This adds value beyond the annotations without contradiction.

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

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

The description is two sentences, front-loads the action, and contains no extraneous 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?

Given the single parameter, clear schema, and comprehensive annotations, the description fully covers usage context. It also references sibling tools, making it complete.

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

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

Schema coverage is 100% and the description does not add additional meaning beyond the schema's parameter description. 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 explicitly states 'Delete a previously stored memory by key', which is a specific verb and resource. It also mentions sibling tools 'remember' and 'recall', distinguishing its purpose.

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

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

The description clearly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also instructs to pair with 'remember and recall', providing explicit context and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This adds value beyond annotations without contradiction.

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

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

The description is concise: two sentences plus a bulleted list of use cases. It is well-structured with the main function stated first, followed by the output format, and then usage guidance. Every sentence adds value.

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

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

Given the absence of an output schema, the description sufficiently explains the output (single text blob) and its format (standard llms.txt markdown). It covers the extraction scope and behavior of the tool. With 2 parameters fully described and annotations present, the description is complete for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters ('url' and 'max_links'). The description adds context such as 'default 25, max 50' for max_links, going beyond what the schema provides. It also explains the purpose of the parameters in the context of the tool's function.

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

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

Description clearly states the tool generates a production-ready llms.txt file for a URL. It specifies the action (generate), the resource (llms.txt for any URL), and the benefit (AI crawlers index cleanly). The description also distinguishes it from sibling tools by focusing on this specific output format.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor site. It provides clear context for when to use the tool, though it does not explicitly state when not to use it.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds value by specifying the exact schema details returned, providing behavioral context beyond the annotations. No contradictions.

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

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

The description is a single concise sentence that front-loads the purpose and efficiently communicates the output details with 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 thoroughly lists expected outputs (fields, geometry, count, capabilities) without requiring an output schema. It is complete for the tool's simplicity.

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

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

Schema coverage is 100% for the 'url' parameter, so baseline is 3. The description adds an example URL format and explains what the tool does with the URL, providing additional context.

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

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

The description clearly states the tool retrieves an ArcGIS layer's schema, listing specific attributes (fields, geometry type, record count, capabilities). This specificity and differentiation from siblings like query_layer make purpose very clear.

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

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

The description implies usage for retrieving schema metadata but does not explicitly guide when to use this tool versus alternatives or when not to use it. It lacks explicit usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return fields and scopes to caller's subscriptions, adding value without contradiction.

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

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

Two sentences, front-loaded with purpose, every sentence earns its place.

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

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

Simple tool with one optional param and no output schema, but description lists return fields. Complete for its complexity.

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

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

Schema covers 100% of parameter description. Description does not add extra meaning beyond the schema for the only parameter. Baseline 3.

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

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

Clear verb-list and resource-subscriptions. Distinguished from siblings like subscribe/unsubscribe.

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

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

States when to use: review monitoring before adding more or to find an id to cancel. Not explicit when not to use, but adequate for a simple list.

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

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

Discloses rate limit (5 per identifier per day), free usage, no quota impact, and that the team reads digests daily. Adds behavioral context beyond annotations, which only indicate readOnlyHint=false etc.

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 yet comprehensive, with each sentence providing essential information. Front-loaded with core purpose, followed by guidelines and constraints. No wasted words.

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

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

Covers all essential aspects: purpose, use cases, parameter details, constraints (rate limit, free, quota), and expected behavior (team reads daily). No output schema is needed for this feedback tool as the action is fire-and-forget.

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

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

Schema coverage is 100% and the description adds value by elaborating on enum meanings, providing usage guidance (describe in terms of tools/packs), and explaining the optional context object's purpose.

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 'Tell' and the resource 'Pipeworx team' with specific categories (bug, feature/data_gap, praise). It distinguishes from siblings by focusing on feedback, which no other sibling tool addresses.

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

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

Explicitly lists when to use each category (bug, feature/data_gap, praise) and provides an exclusion (don't paste end-user prompt). Also mentions rate limits and that it's free, giving clear context for 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, openWorldHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds value by stating the data source ('CF analytics-engine'), privacy guarantee ('no PII'), and caching duration ('5min-1h depending on window'), which are not in 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 (4 sentences), front-loaded with the primary action, and each sentence serves a purpose: what it returns, use cases, data source, and caching. 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?

For a tool with one optional parameter and no output schema, the description fully explains the return structure (top tools, top packs, total call volume) and the implications of the window parameter, making it complete.

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

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

Schema coverage is 100% with enum constraints and descriptions. The description adds contextual semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps the agent choose the appropriate window.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a configurable window, specifying the verb 'returns' and the resource (trending usage data). It distinguishes itself from sibling tools like 'discover_tools' by focusing on aggregated trending data.

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

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

The description lists three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It also mentions caching behavior. While it doesn't explicitly state when not to use it, the provided use cases are clear and helpful.

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

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

Discloses internal logic: monotonicity violations, partition-sum checks, Jaccard similarity (>=0.30), placeholder slug filters (>20% placeholder fraction returns null), and fill check (theoretical vs realizable edge). Annotations already mark it as read-only, idempotent, non-destructive, and description adds extensive context without contradiction.

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

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

The description is long and dense, but given the tool's complexity (three modes, internal checks), the detail is necessary. It front-loads the core purpose but could benefit from better structuring (e.g., bullet points or sections). Still informative without excessive wordiness.

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

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

Despite no output schema, the description lists response fields (opportunities[] with gap_pp, suggested_trade, etc.) and explains the fill check and when not to trade. It also mentions custom sizing via polymarket_fill_risk. No apparent gaps for an agent to use the tool correctly.

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

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

Schema coverage is 100% with brief descriptions. The description elaborates on each parameter's behavior: event walks child markets, topic searches related events, and explains cross-event mode catching patterns missed by single-event. Adds value beyond schema, but schema already provides adequate basics.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage detection.

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 no args (trending_scan), event, or topic modes, and mentions polymarket_fill_risk for custom sizing. It contrasts cross-event vs single-event modes, providing clear decision criteria.

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, idempotent, and non-destructive behavior, which the description confirms. Description goes far beyond annotations by detailing the three model segments, cache duration (1h KV-level), and output structure including diagnostics for empty results. 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 long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.). Front-loaded with core purpose. However, it includes extensive technical detail that could be condensed without losing key information, making it somewhat verbose for an AI agent.

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, so description fully covers return structure: by_segment with three sub-objects, fed_candidates/fed_note, and _diagnostics explaining why segments are empty. Also explains caching and per-opportunity fields. Completely sufficient for an agent to understand and 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%, so baseline is 3. The description adds context for each parameter (e.g., slippage_pp explains zero fees but bid/ask depth, min_kelly explains it applies to single-leg opportunities, min_partition_leg_kelly clarifies partition filtering). Provides default values and usage examples, adding meaning beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx's proprietary model families and daily scanning.

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

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

Explicitly says built for 'what should I bet on today' and that agents use it to discover opportunities without paging through hundreds of markets. Provides guidance on parameter knobs (e.g., min_liquidity, max_spread_pp) and tradeable-edge filters. Lacks explicit when-not-to-use but offers sufficient context for 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, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral traits beyond annotations: snapshot reading, decay computation from daily closes, history bounded by TTL and snapshot start. 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 densely packed with useful information but is somewhat long. It is front-loaded with the key question. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool complexity (two optional parameters, no output schema, related sibling tools), the description covers purpose, usage, behavior, parameters, output format, and limitations. It is fully sufficient for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining defaults (days default 14, window default '1wk'), the meaning of window as snapshot family, and how parameters affect the response structure. This exceeds 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 the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes between fresh and old edges, differentiating from sibling tools like polymarket_edges which likely provide raw current edges.

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

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

The description explains the tool's purpose and when to use it (to understand edge history and decay). It implies context and mentions limits (60-day TTL, not intraday). While it doesn't explicitly name alternatives, the sibling list and focus on historical tracking make usage clear.

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

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

Description adds detailed behavioral context beyond annotations: explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), ladder walking, and basket per-leg details. Annotations already indicate read-only and idempotent; description enriches with operational specifics.

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

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

Well-structured with clear sections and front-loaded purpose. Every sentence adds value, though slightly verbose for a concise definition. Minor redundancy could be trimmed, but overall effective.

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

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

Given no output schema, the description fully documents all return values and edge cases for both modes. Covers thin legs, directional risk, and partial fill consequences. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions, but the description adds crucial nuance: explains size_usd interpretation for single-market vs basket, side defaults and auto-detection, and mode selection via market/event. This adds meaningful context 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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishes two modes (single-market and basket), and specifies parameters. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains when not to use it (thin books, partial fills). Provides clear context with 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?

Goes far beyond the read-only and idempotent annotations by detailing response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and explaining edge cases where spreads are meaningless. No contradiction with annotations.

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

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

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with purpose. While lengthy, every sentence contributes information. Could be slightly more concise by grouping safety fields, but overall efficient for the complexity.

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

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

Despite no output schema, the description thoroughly explains output fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross). Covers potential issues like temporal misalignment and non-equivalent bet shapes. Complete for a complex tool with no output schema.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by explaining the two modes, providing example values, and clarifying override behavior. Additional context like 'pre-mapped macros' and auto-fetching behavior enhances understanding beyond the schema.

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

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

Clearly states cross-venue spread computation between Kalshi and Polymarket. Distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than single-venue arbitrage. The two modes (topic shortcuts and explicit identifiers) are well defined.

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?

Describes when to use each mode and warns that pre-mapped topics may not always yield tradeable spreads, explicitly cautioning 'pre-mapped ≠ tradeable'. Provides conditions where compatibility_warning fires, indicating no arb exists. Could be more explicit about alternatives like polymarket_arbitrage when only one venue is of interest.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it returns attribute rows and geometry, which is beyond annotations. No contradictions.

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

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

Two sentences: first defines, second gives example. Concise and front-loaded with the core purpose. Could be slightly more structured but 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?

No output schema, but description mentions returns (attribute rows and geometry). Covers purpose, parameters, and return type adequately for a simple query 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 description coverage is 100%, baseline 3. Description adds context by noting SQL-like syntax, comma-separated fields, and example clauses, enhancing understanding beyond the schema.

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

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

Clearly states it queries an ArcGIS Feature/Map Service layer by URL, specifying the action and resource. Distinguishes from sibling tools like search_datasets and layer_info by focusing on querying data vs. finding or metadata.

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

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

Provides example usage with where='1=1' and out_fields='*' to sample, offering practical guidance. Does not explicitly compare to sibling tools, but the purpose is clear enough to infer 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 indicate read-only and idempotent. The description adds scoping per identifier and the dual behavior with/without key, which enhances 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?

Three sentences with front-loaded purpose. Every sentence adds value: action, usage examples, scoping, sibling pairing. No redundancy.

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

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

Complete for a simple read tool: explains input behavior, scoping, use case, and relationships. No output schema needed.

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

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

Schema coverage is 100%, so baseline 3. Description adds explanation that omitting key lists all keys, and scoping context, which 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 retrieves a value by key or lists all keys if omitted. It uses specific verbs ('Retrieve', 'list') and resource ('saved value'). It distinguishes itself from siblings by mentioning 'remember' and 'forget'.

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

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

Explicitly states when to use: to look up context without re-deriving. Mentions pairing with 'remember' and 'forget' for save/delete, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable context: returned fields, filter options, mark_read effect on subsequent calls, and an alternative API endpoint. This enriches the agent's understanding beyond the annotations.

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

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

The description is four sentences, each earning its place: main purpose, returned fields, filtering options, and note on mark_read and alternative access. No fluff, well-structured, and front-loaded with the action verb 'Pull'.

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 covers key aspects: what it returns, filtering, and mark_read behavior. It also mentions an alternative REST endpoint. Missing details like default ordering or pagination limits, but sufficient for a straightforward polling tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description goes further by providing an example for 'type' (sec_8k), clarifying the effect of 'mark_read' (only newer ones on next call), and reinforcing 'since' as an ISO timestamp. This adds meaningful context 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 pulls fired events from the subscription feed and lists the returned fields (source, citation_uri, raw event payload). It distinguishes itself from general tools like 'recent_changes' by focusing on alerts, but does not explicitly compare to sibling tools.

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

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

No guidance on when to use this tool versus alternatives like 'list_subscriptions' or 'recent_changes'. While it explains usage patterns (filtering, mark_read), it lacks explicit when-not and alternatives.

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

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

The description adds significant detail beyond the annotations: it fans out to multiple sources, handles rate limits and API sunsets, returns structured data grouped by source with citation URIs, and explains the 'since' parameter format. There is no contradiction with annotations.

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

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

The description is concise yet comprehensive, using examples and clear structure. Every sentence adds value: purpose, sources, fallbacks, parameter details, and comparison to sibling. No redundant information.

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

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

Given the tool's complexity (multiple sources, fallbacks, parameter nuances, no output schema), the description covers all necessary aspects: what it does, how to use parameters, edge cases, and return structure. It is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds extra context for the 'since' parameter (relative formats like '7d', monitoring default) and 'value' (ticker or CIK). This goes beyond the schema descriptions.

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

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

The description clearly states the tool returns a change feed for a company over a time window, providing example queries like "What's new with X" and listing specific data sources (SEC EDGAR, GDELT, GNews, USPTO). It is distinct from the sibling tool entity_profile, which is for static profiles.

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 use cases (recent changes) and an alternative (entity_profile for static profiles). It also explains fallback behavior between GDELT and GNews. However, it does not explicitly state when not to use the tool or exclude other siblings.

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

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

Annotations indicate idempotent and non-destructive; description adds retention policy (24 hours for anonymous, persistent for authenticated) and scoping by identifier, going beyond annotations.

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

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

Three sentences cover purpose, usage, and behavior with no unnecessary words. Front-loaded with core 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?

Complete for a store tool: explains what, when, how long, and pairing. No output schema needed.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds example keys (e.g., 'subject_property', 'target_ticker') which provide context 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 'Save data the agent will need to reuse later' and specifies across conversations/sessions. It pairs with recall and forget, distinguishing it from siblings.

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

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

Explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again' and mentions pairing with recall and forget for retrieval/deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it cascades through multiple endpoints, auto-disambiguates, and returns citation URIs. This complements annotations well, though it could mention any rate limits or data freshness.

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 purpose. It is fairly concise given the information conveyed (supported types, input formats, output structure). Minor room for tightening, but overall efficient.

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

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

The description fully covers what the agent needs: when to use, input types, output format, and internal cascading. Without an output schema, it sufficiently explains return values for each type.

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

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

Schema covers both parameters (type, value) with descriptions. The description enriches meaning by detailing return types per type (e.g., company returns ticker + CIK + name + citation; drug returns RxCUI + ingredient + brand + citation). It also explains auto-disambiguation for company names.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with concrete examples like 'What's the ticker for…' and explicit purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It distinguishes from sibling tools by focusing on entity resolution.

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

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

Explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This is clear and actionable. It also explains that the tool replaces 2-3 manual lookups, implying efficiency. No exclusion criteria are provided, but the positive guidance is strong.

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

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

The description reveals that the tool calls ai_visibility_check for each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. These details go well beyond the annotations, which already mark it as read-only, idempotent, and non-destructive. 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 two tightly written sentences plus an illustrative example. Every word adds value, with no redundancy or filler.

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

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

For a tool with 4 parameters, no output schema, and comprehensive annotations, the description fully covers purpose, methodology, return format, and example usage. It equips an agent to correctly invoke and interpret results.

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: for 'entities', it clarifies that the first entry is treated as subject; for 'models', it explains defaults and API key requirements. This additional context elevates the score 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 uses specific verbs ('Compares', 'Probes', 'ranks', 'surfaces') and clearly identifies the resource (AI visibility across multiple entities). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the side-by-side ranking function.

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 ('competitive AI-marketing audits') and an example question. While it doesn't explicitly state when not to use or name alternatives, the context is sufficient for an agent to infer that single-entity checks should use 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, idempotentHint, etc. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This helps the agent understand potential delays and error handling 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 dense but well-structured, starting with the core composite check concept, then listing details, use cases, and notes. It could be slightly more concise, but 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 fully explains what the tool returns: a summary block with specific fields, per-advisory detail, links, and alternative versions. This is comprehensive for an agent to understand the output without relying on a schema.

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

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

Schema coverage is 100% for both parameters. The description adds meaning beyond the schema by noting that scoped packages are accepted for 'package' and that 'version' defaults to the latest published version. This provides useful defaults and input variants.

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

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

The description clearly states it is a composite check for npm packages, covering license, advisories, version history, and bundle size via deps.dev and bundlephobia. It distinguishes from siblings by its specific focus on npm package analysis, which no other tool does.

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

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

The description explicitly says to use it when an agent asks about safety, popularity, size, or cost of adding a package. It also notes the scope (npm ecosystem only) and where to go for other ecosystems (deps.dev:version directly). This provides clear usage context, though it could mention specific sibling tool names for alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the returned fields (name, summary, record_count, owner/org, url) and the intended next step, going beyond annotations.

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

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

The description is two sentences, front-loaded with the key purpose and examples. Every sentence is necessary and efficiently conveys core information without redundancy.

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

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

Despite no output schema, the description explains return fields and how to use the result. It covers all parameters (all optional) and connects to sibling tools, making it self-contained for this search tool.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description provides examples but adds no significant semantic information beyond the schema's parameter descriptions.

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

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

The description clearly states the tool searches GIS open geospatial datasets by keyword, specifying the resource (City of San Bernardino datasets) and action (search). It mentions the return fields and links to sibling tools, distinguishing it from others.

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

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

The description explicitly instructs to pass the returned URL to query_layer/layer_info, providing clear downstream usage. However, it does not explicitly state when not to use this tool or mention alternatives for similar searches.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the embedding model (BGE-base-en), chunking method (500-char overlapping windows), character limit (200K chars with truncation flag), and that results include character offsets and similarity scores. This provides full transparency for the agent.

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, then provides use-case guidance, and finally technical details. Every sentence adds value without repetition or fluff. It is well-structured and concise.

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

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

Given the tool's complexity (semantic search, chunking, truncation) and the absence of an output schema, the description fully explains what the tool returns (top-N passages with offsets and similarity scores), its limitations (200K char cap, truncation flag), and its technical mechanism. No gaps remain for an agent to understand proper usage.

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 providing example queries, explaining the 'text' parameter as document text, and clarifying the 'limit' parameter default and range. This extra context elevates it above 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 the tool performs semantic search inside a fetched record, using specific verbs ('search within') and resource ('a fetched record'). It distinguishes itself from siblings by mentioning how it pairs with 'ask_pipeworx_grounded' and explicitly contrasting with using large records in prompts.

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

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

The description explicitly states when to use this tool: 'when the record is too big to cram into the prompt'. It also provides guidance on pairing with 'ask_pipeworx_grounded' and explains the benefit of saving context and returning only relevant passages.

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 non-read-only, non-destructive, idempotent. Description adds authentication requirements, type-specific parameters, SMS cap, phone verification, and webhook auto-disable on failures.

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 well-structured with purpose, requirements, types, and delivery sections. Some repetition could be trimmed, but it remains readable.

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 authentication, type-specific params, delivery options with constraints, and return format. No output schema, but description partially compensates. Lacks explicit response type for subscription ID.

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

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

Schema coverage is 100%, but description enriches with concrete examples for each type's params and delivery options, 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?

Description clearly states 'Create a proactive monitoring subscription' and mentions return value. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 requires Pipeworx OAuth account and notes anonymous/BYO cannot persist. Provides supported types and delivery channels with constraints, helping agent decide when 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 confirm read-only, idempotent, non-destructive, and open-world nature. The description adds beyond by detailing the output format (category-bucketed examples with exact tool+argument shapes) and the fact that it draws from a live catalog of thousands of tools.

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 alternative phrasings, then concisely states purpose, output, usage, and when to use. Every sentence adds value, and the structure is 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?

For a simple tool with one optional parameter and no output schema, the description fully covers all relevant aspects: purpose, behavior, usage, and context. No information gaps remain.

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

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

Schema coverage is 100% with one documented parameter. The description adds nuance by explaining the purpose of each optional topic (e.g., finance, pharma) and that omitting the topic yields a cross-category spread, which goes beyond the schema's simple list of values.

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 category-bucketed example questions with tool call shapes, distinguishing it from siblings like ask_pipeworx or entity_profile.

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

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

Explicitly instructs to use this tool FIRST when unfamiliar with Pipeworx's capabilities, and provides guidance on when to omit or specify the topic parameter. It also references sibling tools as things to learn about.

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

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

Discloses beyond annotations: deactivates row (not deletes) so historical events remain via recent_alerts. Annotations already indicate idempotent and non-destructive; description adds concrete behavioral details.

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

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

Two highly informative sentences with zero waste. Front-loaded with action and resource, then adds constraints and side effects.

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 simple tool (1 param, no output schema) and annotations present, description fully covers purpose, constraints, side effects, and outcome. 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 already covers the single parameter (id) fully. Description adds that id is a UUID returned by subscribe, linking to another tool. Baseline 3 with added context gives 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?

Clearly states 'Cancel a subscription by id.' Uses specific verb and resource, and distinguishes from siblings 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?

Explicitly says ownership is enforced and you can only cancel your own subscriptions. Implicitly tells when to use (when you want to cancel your own subscription) and when not (can't cancel others'). No explicit mention of alternatives, but context from sibling names provides this.

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, etc. Description adds valuable behavioral context: it returns a verdict, structured form, actual value with citation, and percent delta. It also describes the source system (SEC EDGAR + XBRL) and version limitations, 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 moderately sized and front-loaded with purpose and usage. It includes a list of return values which, while helpful, adds some clutter. Overall, every sentence adds value without being overly verbose.

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 1 parameter and no output schema, the description is highly complete. It explains what the tool does, when to use it, what inputs are expected, what outputs are returned, and the domain limitations. An agent would have sufficient information to decide 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?

Only one parameter 'claim' with full schema description coverage. The description adds examples and explains how the claim is interpreted (natural-language, factual claim). This goes beyond the schema's basic description, providing richer semantics.

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

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

The description clearly states the tool is for verifying natural-language factual claims against authoritative sources, listing example queries and specific scope (company-financial claims). It distinguishes itself by noting it replaces multiple sequential calls and provides a verdict with evidence.

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 whenever the agent needs to check whether something a user said is factually correct' and specifies scope (v1 supports company-financial claims via SEC EDGAR). Does not explicitly state when not to use or name specific sibling alternatives, but the context is clear.

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