Arcgis Sanclemente

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds cost behavior (Anthropic charges) and default model behavior beyond annotations.

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

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

Two well-structured sentences that front-load purpose and provide key details. Almost no filler, but could be slightly more organized with bullet points for parameters.

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 purpose, use cases, parameter behavior, and return format (per-model fields + combined view). No output schema, but description provides enough return structure for an agent to understand what to expect.

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

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

Schema coverage is 100%, and description enriches each parameter with examples and context: entity examples, models omission default, _apiKey requirement only when needed, context disambiguation help. Adds significant value.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility 0-100 per model. It distinguishes from sibling tools like ask_pipeworx and entity_profile by focusing on AI visibility scoring across multiple models.

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

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

Explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifications on default model and when to use _apiKey. Lacks explicit when-not-to-use but provides good context for selection.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description adds value by detailing the routing to many sources, citation format, and that it works on all tiers. It does not contradict annotations, and provides additional context beyond the structured fields.

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

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

The description is relatively long but every sentence adds value: stating preference, listing data types, explaining routing, providing usage guidance, examples, and alternatives. It is front-loaded and well-structured, 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 of 33 sibling tools and no output schema, the description covers the tool's role, when to use it, and what it returns (structured answer with citations). It is sufficiently complete for an AI agent to decide on invoking it.

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

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

The input schema covers all 6 parameters with descriptions, achieving 100% coverage. The description does not add significant meaning beyond the schema; it mentions aliases but those are already listed. Baseline 3 is appropriate.

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

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

The description clearly states that the tool routes questions to one of many tools across verified sources and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when each is appropriate.

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

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

The description explicitly advises preferring this tool over web search for many data types, provides example queries, and gives step-up guidance for alternatives when different characteristics are needed (e.g., 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds key behavioral details: extra LLM cost, explicit refusal on failure, and grounding extraction via only tool result. 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 detailed but well-structured: front-loaded purpose, then behavior, then usage guidance. Every sentence is useful, no fluff. Length is justified by 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?

No output schema, but description fully explains return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and possible refusal reasons. Also covers trade-off (extra LLM call) and compares to sibling.

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. Description adds value by listing aliases (q, text, input, query, prompt) beyond what schema provides. However, does not add syntax or format details, so slightly above baseline.

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

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

The description clearly states it's a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: picks tool, fetches data, extracts answer using only tool result. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded answers.

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: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Provides clear context for decision-making.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds significant detail: low-confidence short-circuit, closed market handling, wide-spread indicators, resolution-rule risk, parent event extraction, news fallback, safety mechanisms, and response shapes. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (purpose, classifiers, fan-out examples, response shapes, etc.). It front-loads the core purpose. While verbose, the complexity of the tool justifies the length, and every section 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 tool's complexity (3 parameters, no output schema, multiple edge cases), the description covers all necessary aspects: match confidence, parent events, news fallback, safety, market closure, wide spreads, and resolution rules. It is comprehensive enough for an agent to understand invocation and result interpretation.

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 three parameters (market, depth, include_raw). The description adds significant value beyond schema by explaining the depth levels (quick vs thorough), providing examples for market input (slug, URL, question text), and clarifying the meaning of include_raw (summarized vs full payloads).

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, resolves markets, classifies bets, fans out to data packs, and returns evidence packets. It distinguishes itself from siblings by focusing specifically on Polymarket bets, with explicit use cases like 'should I bet on X'.

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

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

The description explicitly states when to use the tool ('Use for should I bet on X...') and provides extensive examples of different bet types and fan-out patterns. It does not explicitly list when not to use it, but the focus on Polymarket makes the context clear.

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

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

The description adds significant detail beyond the annotations: it explains data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is fairly comprehensive but slightly verbose. It front-loads trigger phrases and core functionality, and every sentence adds value. Could be tightened slightly but still well-structured.

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

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

Given the tool's complexity (two entity types, multiple data sources, citation URIs), the description covers all essential aspects: when to use, what it does, data sources, sorting, and output format. No output schema exists, but the description adequately describes return values.

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

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

The schema has 100% coverage, but the description adds deeper context: explains the meaning of 'type' values (company vs drug) and specifies the format for 'values' (tickers/CIKs for company, drug names for drug), along with data sources and behavior.

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, pulling specific financial or clinical data. It distinguishes itself from sequential single-pack lookups and provides trigger phrases.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and lists trigger phrases like 'which is bigger / better...', giving clear guidance on when to use this tool and what to prefer over alternatives.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds critical behavioral context: account requirement, free vs paid tiers, parallel decomposition, return format (findings packet with fields), time expectation (15-60s), and that it never invents (gaps[]).

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

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

The description is somewhat verbose but well-structured: account info first, then core functionality, then comparisons and time estimate. Every sentence adds value, but it could be tightened slightly.

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

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

Given the tool's complexity and lack of output schema, the description fully covers what the tool does, how it works, what it returns, and when to use alternatives. No gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that depth='thorough' requires a paid plan, which is not in the schema. Otherwise, it aligns with 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 performs grounded multi-source research across Pipeworx's 1160 structured data sources in one call, explicitly distinguishing it from open-web search and sibling tools like ask_pipeworx.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: recommends ask_pipeworx for single lookups and breaking news, notes account requirements, and specifies depth levels. It also explains when results may be empty.

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 true and destructiveHint false. The description adds value by explaining that results include full schemas with curated examples and that each result is ready to call without a second lookup. 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 moderately long but front-loaded with the core purpose and examples. Every sentence adds value (examples, invocation advice, return format). Could be slightly more concise but is well-organized.

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

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

Despite lacking an output schema, the description fully explains what is returned (top-N tools with names, descriptions, full schemas with examples, ready to call). It covers purpose, usage context, parameter aliases, and return behavior, making it complete for a meta-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% for all 6 parameters. The description explicitly groups several aliases (query, q, task, search, description) and explains that 'query' is the primary natural language input, adding clarity beyond individual 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 'Find tools by describing the data or task' and provides numerous concrete examples (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by specifying that it discovers tools (not data) and returns their schemas for immediate invocation.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context on when to use, though it doesn't explicitly state when not to use or list specific alternatives beyond the sibling tool set.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds valuable context: parallel fan-out across sources, specific returned fields, USPTO sunset and soft-fail behavior, and fallback mechanisms.

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

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

Front-loaded with example queries, then lists behavior and sources efficiently. Every sentence provides utility; no redundancy or vagueness.

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 output schema, description thoroughly explains return structure (CIK, filings with URIs, fundamentals, patents, news, LEI). Covers edge cases like name-only input and sunset dates.

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

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

Schema has 100% coverage with clear descriptions for both parameters (type enum, value string). Description reinforces and adds nuance: only 'company' supported, ticker or zero-padded CIK, names not supported.

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 'full cross-source profile of a US public company in ONE parallel call' with numerous example queries. Distinguishes from chaining single-source lookups and 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?

Explicitly says to use when user asks for a holistic view, and to prefer over chaining. Also specifies input constraints (ticker or CIK, not names) and directs to resolve_entity if only a name is available.

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. The description adds context about clearing sensitive data, but the behavioral disclosure is largely covered by annotations. No contradiction.

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

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

Two concise sentences with no wasted words. Front-loaded with the core action and immediately followed by usage context.

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

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

For a simple one-parameter delete tool with full annotations, the description provides complete information: what it does, when to use, and related tools. 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 the description of 'key' as 'Memory key to delete'. The description adds no additional meaning beyond the schema, so baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when-to-use scenarios: stale context, task completion, or clearing sensitive data. Also mentions pairing with 'remember' and 'recall', offering clear guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds behavioral details: fetches page, extracts metadata, emits standard markdown. No contradictions. It could mention rate limiting or auth needs, but not necessary for a read-only tool.

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

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

Three sentences, each adding unique information. Front-loaded with purpose, followed by process and use cases. 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?

The description explains what input is needed, what the output is (single text blob), and where to place it. No output schema needed given simplicity. Covers all essential context for 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 covers 100% of parameters. Description adds default and max for 'max_links' and an example for 'url', but does not provide significant extra meaning beyond the schema.

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

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

The description clearly states the verb 'generate' and the specific resource 'llms.txt file for any URL'. It also distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

The description explicitly lists three use cases (client site, own project, competitor audit) and implies when to use. It does not explicitly state when not to use or provide 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.

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 specific behavioral details about the schema elements returned (fields, geometry type, record count, capabilities), which goes 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, well-structured sentence that immediately conveys the tool's purpose. It mentions the key outputs without any extraneous information.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers the core functionality well. However, it lacks any mention of prerequisites like authentication requirements or potential error conditions, which would make it more complete.

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

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

The input schema covers the single parameter 'url' with a description, achieving 100% schema coverage. The main description does not add further meaning to the parameter beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Get' as the action, 'ArcGIS Feature/Map Service layer's schema' as the resource, and enumerates what is returned (fields, geometry type, record count, capabilities). This distinguishes it from siblings like 'query_layer' which likely retrieve 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 does not provide any guidance on when to use this tool vs alternatives. It does not mention when not to use it or suggest other tools for different needs, such as querying actual features.

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 non-destructive behavior. The description adds that it returns specific fields and defaults to active subscriptions, but does not introduce new behavioral context beyond annotations.

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

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

Two concise sentences: first states the action and return fields, second gives usage guidance. No unnecessary words, front-loaded with key information.

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

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

For this simple list tool with one optional parameter and strong annotations, the description fully covers return fields, default behavior, and when to use it, making it complete for an agent.

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

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

The input schema has 100% description coverage for the single optional parameter 'include_inactive'. The description does not add additional parameter-level meaning beyond what the schema already provides.

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

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

The description clearly states it lists the caller's active subscriptions with specific return fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe' which are mutation tools.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context for when to use it versus 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?

Adds important behavioral context beyond annotations: rate-limited to 5 per day, doesn't count against quota, team reads digests daily. 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?

Every sentence adds value: purpose, usage scenarios, parameter guidance, rate limits, impact. Front-loaded with main action. 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 necessary aspects for a feedback tool: what, when, how, constraints, and impact. No output schema needed for a simple feedback endpoint.

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

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

Schema descriptions cover all parameters. Description adds valuable guidance: describe issue in terms of tools/packs, don't paste user prompts. Adds nuance beyond enum labels.

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 the tool's purpose: sending feedback about broken, missing, or needed functionality. Distinguishes from sibling tools by being the only feedback mechanism.

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

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

Explicitly specifies when to use each feedback type (bug, feature/data_gap, praise). Also mentions rate limits and that it's free, setting expectations.

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

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

Discloses data source (CF analytics-engine), no PII, output format (pack, tool, count), and caching behavior (5min-1h). Adds value beyond annotations which already declare readOnly, idempotent, non-destructive.

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

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

Two sentences plus a bullet list, all front-loaded with the main purpose. Every sentence earns its place with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, use cases, behavior, and parameter details 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 coverage is 100% with a description for 'window'. The description adds semantic meaning: shorter windows for hot now, longer for steady-state demand.

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 what other AI agents are calling on Pipeworx, specifying the resource (trending calls) and verb (returns). It is distinct from siblings, none of which directly overlap.

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

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

Provides three explicit use cases: discovering hot data sources, confirming canonical tools, and seeing alignment. Also contrasts window options for different needs. Clear guidance on when to use.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: partition sum should ≈1 with >3pp deviation signaling, semantic anchor requiring Jaccard similarity ≥0.30, partition filter for placeholder slugs, and fill check logic. 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 long but well-structured with clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the purpose. Every sentence adds value, though some details (e.g., exact output format) could be more concise. 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?

Given no output schema, the description fully explains returned fields: opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered; and fill check outputs. It covers edge cases (low similarity, placeholders, thin legs) and references sibling tool for custom sizing, making it self-contained for an agent.

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

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

Schema coverage is 100% with descriptions. The description enriches parameters with examples (e.g., 'fed-decision-may-2026'), explains processing (walks child markets, computes partition_check), and adds context for event and topic modes. Slightly redundant with schema but adds valuable meaning.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three call modes (no args, event, topic) with specific examples. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk, establishing a unique 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 provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. It also advises when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing, covering both usage and exclusions.

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

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

The description goes far beyond annotations by detailing caching behavior (cached 1h at KV level keyed on all knobs), edge computation methodology (slippage, Kelly fractions, model families), filter impact, and diagnostics output. No contradiction with annotations exists, and the description adds substantial operational context.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs. It is front-loaded with the core purpose in the first sentence, but the extensive detail on model families and filters could be condensed. While valuable, it exceeds optimal conciseness for an LLM to quickly parse.

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 thoroughly covers the return structure (by_segment, diagnostics), edge properties, and tradeable-edge knobs. It explains why segments might be empty and includes caching details. This is complete for an agent to understand inputs, outputs, and behavior without external docs.

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

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

Schema coverage is 100%, so the description is not required to repeat parameter details. It does add some contextual connection between parameters (e.g., how min_kelly and min_partition_leg_kelly interact), but this is not per-parameter enrichment. The baseline of 3 is appropriate given the schema already handles 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and contrasts with sibling tools by focusing on edge detection. The detailed breakdown of segments (model_driven, structural_arbitrage, concentrated_longshot) further clarifies purpose.

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

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

The description explicitly states the tool is 'Built for what should I bet on today' and positions it as an alternative to paging hundreds of markets. However, it does not explicitly provide when-not-to-use guidance or compare to siblings like polymarket_arbitrage or polymarket_fill_risk. The context is clear but lacks formal exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details beyond annotations: it explains that the tool reads daily snapshots, computes trend and decay using |edge_pp_net| daily closes (not intraday), and that gaps occur when polymarket_edges runs on a cache-miss. 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 5 sentences long, front-loaded with the core purpose. It is structured into purpose, response format, and limits. While comprehensive, it could be slightly more concise; for instance, the detailed response breakdown could be abbreviated. Still, every sentence contributes.

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 thoroughly documents the response structure (tracked, expired, snapshot_dates) with field explanations, edge cases (gaps, first_seen, median lifespan), and limitations (60-day TTL, daily closes). This fully compensates for the missing 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% with brief parameter descriptions. The description adds value by providing context: default values (days=14, window='1wk'), clamp range for days (2-30), and explanation of window as 'snapshot family'. This goes beyond mere schema repetition.

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: 'Answers how long has this edge existed and is it shrinking?' and explains the distinction between fresh and old edges. It specifies the exact output (tracked edges with time-series, trends, expired edges), distinguishing it from sibling tools like 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?

The description provides implicit usage context by contrasting fresh wide edges with 3-week-old edges, and includes LIMITS section detailing constraints (60-day TTL, gaps). However, it does not explicitly state when to use this tool versus alternatives like polymarket_edges, so it falls short of a 5.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds extensive behavioral context: it requires one of 'market' or 'event', details return fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and mentions risks like forced_directional_risk and partial basket fills. 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 well-structured, front-loading the purpose then breaking into details. It is fairly long but each sentence contributes value. Minor redundancy could be trimmed (e.g., repeating 'single-market mode' after already introducing), but overall it is 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?

Given the tool has 4 parameters with 100% schema coverage, no output schema required, the description fully outlines the return fields for both modes (top_of_book, shares_filled, etc.) and explains behavioral aspects like forced_directional_risk. It is complete for an AI agent to understand what the tool does, what it returns, and when to use it.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the 'side' parameter values for both single-market and basket modes, clarifies 'size_usd' interpretation (spend vs settlement notional), and provides defaults. It also clarifies the difference between 'market' and 'event' parameters. This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the name 'polymarket_fill_risk' aligns with the goal of assessing fill risk. Among sibling tools like polymarket_arbitrage and polymarket_edges, this tool is uniquely positioned for pre-trade risk checks.

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

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

The description explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why—theoretical overround on thin books is not capturable and partial basket fills can turn an arb into an unhedged position. This provides clear when-to-use guidance and references sibling tools as alternatives.

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

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

Beyond annotations (readOnly, idempotent), description details safety fields, compatibility warnings, temporal alignment checks, skipped cross types, and the fact that many shortcuts return warnings. This provides deep behavioral context.

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

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

Description is front-loaded with main purpose but becomes detailed. While informative, it could be slightly more concise. Nonetheless, structure is logical and every sentence adds value.

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

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

Given no output schema, description fully explains response structure, safety fields, edge cases, and temporal alignment. No missing critical context for using 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%, so baseline is 3. Description adds value by explaining the two modes and how parameters interact (override behavior), and details the topic shortcuts.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb 'cross-venue spread'. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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?

Description explains two modes (topic shortcuts and explicit inputs) and includes caveats about when spreads are meaningful. However, it does not explicitly exclude alternatives or state when not to use this tool compared to similar 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 already declare readOnlyHint=true and destructiveHint=false, so the tool is clearly safe. The description adds behavioral details: returns attribute rows and geometry, uses SQL-like query semantics, and supports pagination. It does not disclose error conditions or rate limits, but the added context is valuable.

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

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

The description is three sentences: first states purpose and parameters, second what it returns, third a usage tip. It is front-loaded, concise, and every sentence earns its place 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 complexity (6 parameters, no output schema), the description covers the main purpose and usage pattern. It could be more explicit about return format details (e.g., geometry encoding), but the combination with high schema coverage makes it nearly complete.

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

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

Schema coverage is 100%, so parameters are already documented. The description rephrases key parameters and adds a usage example (where='1=1'+out_fields='*') which provides semantic value beyond the schema. This elevates it above the baseline of 3.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, listing SQL-like parameters (where, out_fields, etc.) and mentions returning attribute rows and geometry. This is a specific verb+resource that distinguishes it from siblings like layer_info.

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

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

The description includes clear context for usage ('Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets)') and provides a practical example ('Use where="1=1" + out_fields="*" to sample'). It does not explicitly exclude alternatives or state when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping context (anonymous IP, etc.) but doesn't conflict 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?

Three sentences, front-loaded with action, no wasted words. Clearly 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 annotations and schema, description covers usage, scoping, and pairing with related tools. No output schema, but retrieval tool doesn't require it.

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

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

Schema coverage is 100%. Description adds behavior for omitting key (list all keys), 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?

Description specifies verb+resource ('Retrieve a value previously saved via remember, or list all saved keys') and distinguishes from sibling tools like 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 ('Use to look up context...') and how (omit key to list all). Pairs with remember/forget but lacks explicit when-not-to-use.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds behavioral details: each alert carries source, citation_uri, raw payload; setting mark_read:true flags events read so next call shows newer ones. This provides clear behavioral context beyond the annotations.

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

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

Three sentences with no unnecessary words. The first sentence front-loads the main purpose, and the rest add essential details about return data, filtering, and side effects. 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?

Despite no output schema, the description explains return values (alerts with source, citation_uri, raw event payload), filtering options, and the mark_read side effect. It covers the key behavioral and data aspects sufficiently for this 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 for each parameter. The description adds meaning by giving an example for type (e.g., 'sec_8k'), noting ISO timestamp for since, and explaining the effect of mark_read. This enriches the schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' and 'Returns the most recent alerts', specifying the action and resource. It also distinguishes by mentioning filtering options and the data fields returned, avoiding tautology.

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

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

The description provides context with 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' hinting at polling use and an alternative. However, it does not explicitly state when not to use this tool vs. siblings like list_subscriptions or subscribe.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: it fans out to multiple sources in parallel, has a fallback mechanism (GDELT→GNews), handles API changes (USPTO sunset soft-fail), and returns results grouped by source with citation URIs. No contradiction with annotations.

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

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

The description is a single, dense paragraph that front-loads example queries, then explains sources, parameter details, and sibling distinction. Every sentence provides essential information without fluff, making it highly efficient.

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

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

Despite having no output schema, the description adequately describes the return structure: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It covers complex behaviors like multi-source fanned-out calls and fallback logic, making the tool's behavior sufficiently clear for an AI agent.

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

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

With 100% schema coverage, the description still adds significant value: it explains the two formats for since (ISO date or relative shorthand like '7d'), recommends '30d' or '1m' for typical use, and gives concrete examples for value (ticker or CIK). This goes well beyond the schema definitions.

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

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

The description clearly states this tool provides a change feed for a company over a recent window, listing specific sources (SEC, GDELT/GNews, USPTO) and giving example user queries. It explicitly distinguishes from the sibling entity_profile tool, which is for static profile information.

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

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

The description includes explicit guidance: it explains when to use the sibling entity_profile instead ('Use entity_profile instead when you want the static profile... regardless of window'). It also details the fallback behavior between GDELT and GNews and the soft-fail for USPTO, helping the agent decide when to invoke 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?

The description discloses storage mechanism (key-value, scoped by identifier), persistence duration (24h for anonymous, persistent for authenticated), and pairing with recall/forget. It doesn't explicitly state overwrite behavior, but the idempotent annotation implies that. Given annotations provide some transparency, the description adds meaningful context, earning a 4.

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 (three sentences), well-structured, and front-loaded. Each sentence serves a distinct function (purpose, when to use, how it works, 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?

The description covers purpose, usage, storage, and pairing adequately. It lacks some edge-case details (e.g., overwrite behavior, storage limits), but for a simple tool with good annotations, it is mostly complete. A 5 would require more exhaustive details.

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

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

Schema descriptions provide basic type info. The description supplements with concrete examples of key names and value types, helping the agent understand what to store. Even though schema coverage is 100%, the description adds enough context to merit a 4.

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

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

The description clearly states the tool's purpose as saving data for reuse, provides concrete use cases (resolved ticker, target address, user preference), and explicitly mentions sibling tools (recall, forget) for differentiation.

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

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

The description explicitly states when to use the tool (when discovering something worth carrying forward), provides scenarios, and references complementary tools (recall, forget). It also explains the persistence behavior, aiding decision between persistent vs session memory.

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 provide read-only, idempotent, and non-destructive hints. The description adds that each call cascades through several endpoints and details return values (ticker, CIK, RxCUI, citation URIs). No contradiction with annotations.

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

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

Well-structured with examples front-loaded. All sentences are informative, but the description is somewhat lengthy. Could be slightly more concise while retaining 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 no output schema, the description thoroughly explains return values for both types. With annotations providing safety hints, it covers necessary behavioral and output context effectively.

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

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

Schema coverage is 100% with both parameters described. The description adds value by explaining input formats (e.g., ticker, CIK, name for company; brand or generic for drug) and auto-disambiguation, going 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's purpose: resolving names to canonical identifiers. It gives concrete examples like 'ticker for...', 'find the CIK for...', and specifies supported types. The instruction 'Use FIRST' differentiates it from 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides context for when to use it and mentions it replaces manual lookups. However, it does not explicitly list alternatives or 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, idempotent, and non-destructive. Description adds that it probes each entity via ai_visibility_check and returns ranked list with score, confidence, signal density. No contradictions.

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

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

Two concise sentences plus a parenthetical example. Front-loaded with action, 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?

For a tool with 4 parameters and no output schema, the description adequately explains input semantics (entities order, models, context) and output structure (ranked list with metrics). Mention of underlying tool adds completeness.

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

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

100% schema coverage, but description adds value by explaining the 'subject' role of the first entity and the optional models/default behavior, which is not in the schema.

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

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

The description clearly states the verb (compare/probe/rank/surface), the resource (AI visibility of multiple entities), and distinguishes from sibling tool 'ai_visibility_check' by emphasizing side-by-side comparison.

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

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

Provides explicit use case ('competitive AI-marketing audits') and a concrete question example. Does not explicitly state when not to use, but the context is clear and distinct from 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?

Despite annotations already providing readOnlyHint, idempotentHint, etc., the description adds significant value: it details the composite fan-out across deps.dev and bundlephobia, explains partial failure handling (bundlephobia timeout, graceful degradation), and lists the exact return fields (summary block, advisories, links, alternative versions). 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 a single paragraph but conveys all necessary information efficiently without redundancy. It front-loads the core purpose and progressively adds detail. Minor improvement could be using bullet points for readability, but it remains concise for the amount of content.

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

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

There is no output schema, so the description fully explains the return structure: summary block (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timeout behavior, making the tool's output predictable for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package name, optional version). The description adds minimal extra detail beyond accepting scoped packages, which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a composite check for npm package evaluation, using 'scan' as the verb and specifying the resource as dependencies. It distinguishes itself from sibling tools by focusing on the npm ecosystem and specific checks like license, advisories, bundle size.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes NPM only and mentions fallback for other ecosystems, providing clear context for when to use and when not.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the returned fields (name, summary, record_count, owner/org, url) and that the url is for Feature Service. 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 pack a clear verb+resource, example keywords, list of returned fields, and a directive for using the url. No unnecessary words; front-loaded with key information.

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

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

Given the tool has only 3 optional parameters and no output schema, the description fully covers purpose, output structure, and usage context. It is complete for the complexity level.

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 new meaning beyond what the schema already provides. The description mentions keyword search and output details but does not explain parameter constraints or formats beyond the schema.

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

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

The description clearly states the verb 'Search', specifies the resource 'City of San Clemente GIS open geospatial datasets', and lists example topics (parcels, zoning, etc.). It distinguishes from sibling tools like query_layer by explaining the output url is meant to be passed to those 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 explains what the tool does (search by keyword) and explicitly mentions the output url should be passed to query_layer/layer_info, providing clear next-step guidance. However, it does not explicitly state when not to use this tool or describe alternatives beyond the referenced 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 already indicate idempotent, read-only, non-destructive behavior. The description adds specific technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)', and mentions return includes character offsets and similarity scores. No contradiction with annotations.

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

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

The description is a single paragraph that efficiently communicates core purpose, usage context, behavioral details, and technical inner workings. Every sentence adds value, and it is front-loaded with the main action.

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

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

Without an output schema, the description thoroughly explains what the tool returns: 'top-N passages with character offsets and similarity scores'. It also covers the embedding approach, window size, and length limit. This is complete for a semantic 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 coverage is 100% with good descriptions for all three parameters. The description adds value by providing natural-language examples for the 'query' parameter and clarifying truncation behavior for 'text' (e.g., 'longer inputs are truncated and flagged'). This goes beyond the schema.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb ('search inside'), resource ('record'), and scope ('inside the text you already pulled'). It distinguishes from sibling tools like 'ask_pipeworx_grounded' by explaining how they pair.

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 the record is too big to cram into the prompt' and highlights that it 'saves context'. It also mentions pairing with 'ask_pipeworx_grounded' and explains the benefit. However, it does not explicitly state when NOT to use this tool.

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

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

Annotations indicate idempotence but not read-only or destructive; the description adds significant behavioral context (OAuth requirement, delivery channels, phone verification, rate limits, webhook signing) without contradicting annotations.

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

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

The description is concise given the complexity, with front-loaded action and return value. However, it is dense and could benefit from structure like bullet points.

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 the return value (subscription id), covers all necessary context (prerequisites, types, delivery details, constraints), making it complete for a subscription creation tool.

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

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

Schema coverage is 100%, and the description provides detailed examples and explanations for each subscription type and delivery channel, greatly 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?

The description uses a specific verb 'Create' and resource 'proactive monitoring subscription', clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

It mentions prerequisites (OAuth account) but does not explicitly compare with alternatives such as list_subscriptions or unsubscribe for different use cases.

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 valuable context: returns category-bucketed examples with exact tool+argument shapes, drawn from live catalog. No contradictions.

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

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

Front-loaded with common search phrases. Multiple sentences but each adds value. Could be slightly shorter but remains clear and 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?

Fully covers input (params), output (category-bucketed examples), and use case (onboarding). No output schema needed; description sufficiently explains 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% and describes 'topic' as optional focus area. Description adds a list of possible values (finance, pharma, etc.) and explains behavior when omitted (full spread).

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

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

The description uses specific verbs ('returns', 'call') and identifies the resource (example questions with tool arguments). It clearly distinguishes from siblings by positioning itself as the onboarding entry point and referencing meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Does not explicitly state when not to use, but the use case is clearly scoped.

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

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

Beyond annotations (idempotent, non-destructive), the description reveals key behavioral details: the row is deactivated (not deleted), historical events remain available via recent_alerts. This adds significant context.

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

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

Three sentences with no wasted words. Action and key constraints front-loaded. Perfectly concise 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?

With a single parameter, no output schema, and annotations covering safety, the description fully explains behavior, side effects (deactivation, historical data retention), and ownership rule. 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 parameter 'id' documented. Description adds minimal value by mentioning it's a UUID returned by subscribe, but does not significantly enhance understanding beyond the schema.

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

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

Description clearly states action (cancel subscription), specifies the resource (subscription by id), and distinguishes from siblings like subscribe and list_subscriptions by emphasizing ownership enforcement and deactivation rather than deletion.

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 usage condition: you can only cancel your own subscriptions (ownership enforced). It does not explicitly state when not to use or list alternatives, but the context is sufficient for a simple mutation 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: return types (verdict, structured form, actual value with citation, percent delta) and replaces multiple calls. No annotation 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 multi-sentence but each sentence serves a purpose: listing intents, usage, domain scope, return info, efficiency benefit. No redundancy.

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

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

Given the single parameter, high schema coverage, and no output schema, the description fully covers the tool's behavior, usage, and limitations. It is comprehensive for the 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% and the description adds minimal insight beyond the schema's parameter description. The parameter is straightforward, so baseline 3 is appropriate.

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

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

The description clearly states the tool validates natural-language claims against authoritative sources, provides example intents, and specifies it handles company-financial claims. It distinguishes from sibling tools by noting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check factual correctness' and mentions domain restrictions (company-financial claims for public US companies). It lacks explicit 'when not to use' instructions but the domain restriction implies exclusivity.

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