Arcgis Novi

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

Annotations already indicate safety and idempotency. The description adds beyond that: explains the scoring range, default model, BYO key for Anthropic, and the per-model return structure (score, confidence, signals, raw_response). No contradiction.

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

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

The description is a single concise paragraph (4-5 sentences) with no fluff. It front-loads the main action and output, then explains models, return format, and use cases.

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

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

With no output schema, the description adequately explains the return format (per-model object + combined view). It covers purpose, parameters, and use cases sufficiently. Complete for a tool of this 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%, so baseline is 3. The description adds value by explaining the default model, the purpose of _apiKey (BYO key), and examples for the context parameter. This provides meaningful usage context beyond the schema.

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

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

The description clearly states the tool probes LLMs for entity visibility and scores it (0-100). It specifies the verb 'probe', the resource (LLMs), and the outcome (score). It distinguishes from siblings by focusing on AI visibility scoring for any given entity.

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

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

The description lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly exclude alternatives or compare with sibling tools. Provides clear context for 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 already show readOnlyHint, openWorldHint, idempotentHint. Description adds that it routes to many tools, returns structured answers with stable citation URIs, and is a fast one-call solution. No contradictions, complements annotations well.

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

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

Dense but well-structured: starts with key directive, then scope, then alternatives, then examples, then escalation advice. Every sentence adds value, though could be slightly trimmed without loss.

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, sources, output format, citation URIs, alternatives, example queries, and tier/account notes. No output schema, so description compensates by explaining what agent receives. Fully adequate.

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

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

Schema coverage is 100% with clear parameter and alias descriptions. The description adds value by providing usage examples and explaining what kind of questions work, even though parameter semantics are fully covered by 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?

States it routes questions to 4,476 tools across 1,127 verified sources and returns structured answers with citations. Clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use which.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed criteria with examples. Tells when to use this vs. ask_pipeworx_grounded (hallucination-resistant), deep_research (broad/multi-part), or breaking news. Gives clear directive: 'START HERE for most 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 provide safe-read indicators; description adds detailed behavior on success/failure, including explicit refusal reasons and response structure, enhancing transparency.

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 detailed but somewhat verbose; key info is front-loaded but could be more concise. Still 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?

Given the tool's complexity (routing across 4476 tools) and no output schema, the description adequately covers process, success/failure details, and refusal reasons. Minor gaps in evidence formatting but overall 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 covers 100% of parameters with descriptions; the tool description does not add significant extra meaning beyond 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 states it is a 'Hallucination-resistant answer mode for high-stakes reads' and contrasts with sibling ask_pipeworx, clearly identifying its purpose and distinguishing it.

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' in high-stakes domains) and when to prefer the alternative ('prefer ask_pipeworx for casual lookups').

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, detailing resolution contracts, market matching confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits (low-confidence, closed markets, wide spreads), and resolution-rule risk. It discloses behavioral traits like idempotency, read-only nature, and error handling comprehensively.

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 and front-loaded with the core purpose. Every sentence adds value, covering classifiers, fan-out examples, response shapes, and edge cases. Slight verbosity could be trimmed, but the density of useful information justifies its length.

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 provides exhaustive detail on response shapes, error states (low_confidence_match, market_closed_or_inactive), resolver contract, parent event fields, and safety notes. It covers all necessary context for an agent to correctly interpret responses and handle edge cases.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains how market input can be a slug, URL, or question text; depth defaults to thorough; include_raw describes when to use summarized vs full payloads. This context is crucial for proper parameter use and goes beyond 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and method (pulling Pipeworx data). It distinguishes itself from sibling tools by focusing specifically on Polymarket bets with a rich set of data-fan-out and analysis capabilities.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains the resolver contract and fan-out logic, helping the agent understand when to invoke this tool. However, it does not explicitly compare against sibling tools or state when not to use it, missing a small opportunity for clearer differentiation.

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

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

Beyond annotations (readOnly, idempotent), the description discloses data sources (SEC EDGAR for companies, FAERS/FDA/clinicaltrials for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and return of citation URIs. No contradictions with annotations. This provides comprehensive behavioral understanding.

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

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

The description is well-structured, starting with user-facing query examples, then specifying the action and entity types, then detailing data sources, and concluding with output characteristics. Every sentence adds essential information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (two entity types, diverse data sources, no output schema), the description covers all necessary aspects: what it does, what it returns (paired data + citation URIs), constraints (2-5 items), and how results are sorted. It even mentions off-calendar fiscal year handling. The absence of an output schema is compensated by describing the return format adequately.

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 both parameters fully, with enums and descriptions. The description adds value by providing concrete examples for the 'values' parameter (tickers/CIKs for companies, names for drugs) and clarifying what data each type retrieves (latest 10-K for companies, adverse-event counts for drugs). This goes beyond the schema, but the schema already does most of the work, so a 4 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 specifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one call. It gives example query phrases like 'compare X and Y' and 'X vs Y', making it unambiguous. It also distinguishes from sibling tools by stating it should be preferred over sequential single-pack lookups.

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

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

The description explicitly tells when to use the tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides context for both entity types. It does not explicitly name sibling alternatives, but the guidance to avoid sequential lookups indirectly points to alternatives like entity_profile. A score of 4 reflects clear but not exhaustive exclusion criteria.

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

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

Adds context beyond annotations: account required, parallel decomposition, output format (findings packet with evidence, confidence, source, citation, gaps[]), expected 15-60s response, and behavior for out-of-catalog topics. No contradiction with annotations.

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

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

Description is relatively long but front-loaded with critical account requirement and alternative tool. Each sentence adds value despite some verbosity. Structured logically from requirements to use cases to behavior.

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

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

Given no output schema, description compensates by detailing return format. Covers constraints, use cases, alternatives, and behavior comprehensively. Complete for a complex tool with 2 parameters.

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

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

Schema coverage is 100% (both parameters documented). Description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8) and clarifies question should be broad/multi-part, going beyond 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 the tool performs grounded multi-source research across 1127 structured data sources in one call. It differentiates from sibling ask_pipeworx by noting this is not open-web search and handles broad/multi-part questions.

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

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

Explicitly states when to use (broad/multi-part over structured data), when not to use (single lookup, breaking news) and directs to ask_pipeworx as alternative. Also mentions account requirements and the 'thorough' depth needing a paid plan.

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 idempotentHint=true. The description adds that results include 'full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' which reveals helpful behavior beyond the structured fields. 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 well-structured with the main action first, then usage context, then return value details. It is slightly lengthy but each sentence adds value. Could tighten some phrasing, but overall efficient.

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

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

For a discovery tool with no output schema, the description fully explains the return format (names, descriptions, schemas) and the intended first-call usage pattern. It covers enough context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'query' and 'limit' but does not add substantive meaning beyond the schema's descriptions and examples. The examples in the description mirror those 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 uses specific verbs ('browse, search, look up, discover') tied to the resource ('tools'), and clearly distinguishes from sibling tools by positioning itself as the discovery/browsing gateway. It states 'Call this FIRST when you have many tools available' which differentiates it from individual task-specific 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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available...' Provides clear context and an instruction, though no explicit when-not-to-use or alternatives beyond implying it's for exploration.

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

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

Annotations already indicate read-only and idempotent. Description adds specifics: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists returned fields, and notes USPTO PatentsView may soft-fail. No contradiction with annotations.

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

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

Front-loaded with example queries, but the description is somewhat lengthy. However, every sentence adds meaningful information (supported inputs, return fields, caveats). Could be slightly more concise but still very effective.

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

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

No output schema, so description must explain return values. It thoroughly lists fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and mentions timeframes and sorting. Covers the complexity of multi-source profile.

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 providing examples ('AAPL', '0000320193') and clarifying that names are not supported, which goes beyond the schema's 'description' fields.

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

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

The description starts with clear example queries ('Tell me about X', 'research Acme') and explicitly states the tool returns a full cross-source profile of a US public company. It distinguishes from siblings like resolve_entity, which is used for names.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Also warns that names are not supported and directs to use resolve_entity first. Provides clear when-to-use and when-not-to-use 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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but doesn't reveal further behavioral traits beyond what annotations provide. No contradiction.

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

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

Two sentences, no wasted words. Purpose is front-loaded, and additional usage guidance is succinct.

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 simple tool with one parameter and annotations present, the description covers purpose, usage, and pairing. Could mention irrevocability, but annotations cover destructiveness.

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

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

Only one parameter 'key' with schema coverage 100%. Description does not add extra meaning beyond the schema's 'Memory key to delete'.

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 deletes a memory by key, using specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' by mentioning pairing.

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 (stale context, task done, clear sensitive data) and pairs with alternatives, providing clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds transparency by stating that it fetches an external page, extracts key info, and emits a standard markdown format. No contradictions and no missing behavioral traits.

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

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

The description is three sentences long, front-loading the purpose and output format. It is concise and wastes no words, though it could be slightly more structured (e.g., bullet points for use cases).

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

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

With 2 parameters, no output schema, and comprehensive annotations, the description sufficiently explains input, process, and output format. It mentions the standard llms.txt format and typical file location, making it complete 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%, so baseline is 3. The description adds meaning beyond the schema by explaining that the tool fetches the URL and extracts title/description/key links, which clarifies the url parameter's role. The max_links parameter is well-documented in the schema; the description mentions a default value implicitly (though not explicitly) via 'default 25, max 50' in schema.

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

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

The description clearly states it generates an llms.txt file for any URL, specifying the verb 'Generate' and the resource 'production-ready llms.txt file'. It distinguishes from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on file generation rather than analysis or scanning.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for your own project, or auditing competitor visibility. It implies context but does not provide exclusions or when-not-to-use instructions, leaving room for improvement.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds that the tool returns schema contents by URL and specifies the URL format. It does not contradict annotations and provides moderate additional behavioral context, though it omits details like error handling or rate limits.

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

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

The description is a single sentence that immediately states the action and key output items. It contains no filler or repetition, and every word earns its place.

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

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

Given no output schema, the description adequately covers what the tool returns (fields, geometry type, record count, capabilities). It does not explain how output is formatted or if pagination applies, but for a simple schema retrieval tool this is sufficient.

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

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

With 100% schema coverage and only one parameter, the schema already documents the url parameter. The description adds an example URL format ('.../FeatureServer/0'), which provides minor additional clarity. Baseline 3 is appropriate as the description adds marginal value beyond the schema.

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

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

The description begins with 'Get an ArcGIS Feature/Map Service layer's schema by url', which is a specific verb+resource combination. It lists exact output items (fields, geometry type, record count, capabilities) and the input method (url). This clearly distinguishes it from siblings like query_layer and search_datasets.

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

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

The description implies the tool is for retrieving schema information but does not explicitly state when to use it versus alternatives like query_layer. It provides no exclusions or prerequisites, leaving the agent to infer usage context from the tool name and 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, idempotentHint=true, and destructiveHint=false, so the tool is known to be safe. The description adds value by specifying the exact fields returned (id, type, params, etc.) and implying the default filtering to active subscriptions, which enriches the agent's understanding 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 efficient sentences: first states purpose and return fields, second provides usage guidance. No redundant 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 a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and common use cases (review before adding, find ID to cancel). This is fully adequate for the tool's complexity.

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

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

The single parameter (include_inactive) is fully described in the schema (100% coverage). The description does not add any new semantic information about the parameter beyond stating it lists 'active subscriptions' by default, which aligns with the schema description. Hence baseline score of 3.

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

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

The description clearly states the tool lists active subscriptions, with a specific verb ('list') and resource (subscriptions). It also mentions the return fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises use for reviewing active subscriptions before adding more or finding an ID to cancel. Does not explicitly mention when not to use, but context with subscribe/unsubscribe siblings implies its role as the listing counterpart.

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

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

Discloses rate limit of 5 per day per identifier, that it doesn't count against quota, and that team reads digests daily. Annotations are sparse, so description adds essential 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 effective but slightly verbose; could be trimmed slightly. Front-loaded with purpose and key usage guidelines.

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 3 parameters (2 required) and no output schema, the description fully covers input semantics, rate limits, and usage constraints. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining enum values and message expectations, though schema already has decent 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?

Clearly states the tool's purpose: to tell the Pipeworx team about broken, missing, or needed features. Uses specific verbs and distinguishes from sibling tools like ask_pipeworx or discover_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 provides when to use (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and quota-free usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: cached 5min-1h, derived from CF analytics-engine, no PII, self-aggregating signal. No contradictions.

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

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

Four well-structured sentences, front-loaded with output, then use cases, then technical details. No fluff; 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 low complexity (1 optional param, no output schema, clear annotations), the description is fully complete: covers return values, use cases, caching, and data source. No gaps.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds semantic guidance on trade-offs between short and long windows, enhancing understanding beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, using specific verbs and resources. It distinguishes itself from siblings by focusing on trending aggregation rather than query or discovery.

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

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

Explicitly lists three numbered use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case with demand. Provides context on window semantics and caching.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: walking child markets, checking ordering, computing partition_check, similarity filters, partition filters, and the fill check with live CLOB depth and trading recommendations. It also describes edge cases like placeholder slugs and zero realizable edge. 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 quite long but well-structured and front-loaded with the requirement. Each sentence adds value, but some sections could be more concise. The use of uppercase markers like REQUIRES and SEMANTIC ANCHOR helps readability. It earns its length.

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 arbitrage detection with multiple checks, no output schema, and only two parameters, the description is very complete. It covers the algorithm, response structure, fill check details, and references sibling tools for custom sizing. No gaps identified.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant value beyond the schema: it explains the recommended usage for event (accepts slugs or full URLs), the seed question for topic, and what each mode returns. It also clarifies the semantic anchor and partition filter conditions.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and specifies the exact resources involved. It is very specific and differentiates from siblings like polymarket_fill_risk.

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

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

The description explicitly requires one of 'event' or 'topic' and warns that calling with no args fails. It recommends event for specific markets and explains cross-event mode catches patterns single-event misses. It does not explicitly state when not to use, but the context is clear. It also references the sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavior: caching (1h at KV level keyed on all knobs), model details, edge computation, slippage assumptions, excluded Fed bets, and diagnostics. 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 verbose but well-structured with sections for segments, knobs, and diagnostics. Every sentence provides value, though it could be more concise for an AI agent. Given the complexity of the tool, the length is justified.

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

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

No output schema exists, so the description fully explains the return structure: by_segment with three segments, top-level fields like fed_candidates, and diagnostics that explain why a segment is empty. It also covers caching and exclusion logic. Comprehensive.

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 value beyond the schema. For example, it explains that min_kelly skips small opportunities, and min_partition_leg_kelly applies to per-leg Kelly. The descriptions enrich understanding of each parameter's purpose.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using a specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge detection and provides a detailed breakdown of three segments.

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 it's built for 'what should I bet on today' and describes the scenarios (model-driven, structural arbitrage, concentrated longshot). However, it does not explicitly state when not to use it or mention alternative tools, but the context is clear enough for an agent.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully consistent with the description. The description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), limits (60-day TTL, decay computed from daily closes, not intraday), and the nature of the data (snapshots written on 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 concise despite its length, with every sentence adding critical information. It front-loads the core purpose, then details parameters, response fields, and limits in a logical order. 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?

Given the tool has two optional parameters and no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates with their subfields) and limits. It provides complete context for an agent to understand what the tool returns and its constraints.

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

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

Schema coverage is 100%, and the description adds significant value: it explains 'days' as lookback with default 14 and max 30, with clamp 2-30; 'window' as snapshot family with defaults and options (24hr, 1wk, 1mo). This goes beyond the schema's brief descriptions.

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

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

The description clearly defines the tool as providing edge persistence and decay telemetry from daily snapshots, specifically answering 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (snapshot source) and polymarket_arbitrage, as it focuses on temporally analyzing edge behavior.

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

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

The description gives guidance on when to use (e.g., differentiating fresh vs. old wide edges) and hints at usage via parameters (days, window). However, it does not explicitly state when not to use it or compare directly with alternatives like polymarket_edges, though the context implies it's for historical analysis.

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

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

The description discloses detailed behavioral traits beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint). It explains how it walks the order book ladder, returns metrics like slippage_pp and verdict, and for baskets identifies thin legs and forced directional risk. 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 appropriately sized for the complexity of the tool. It is front-loaded with the main purpose, then details both modes, and ends with usage guidelines. Every sentence provides unique value, and the structure is logical and easy to follow.

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

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

Given the tool has 4 parameters, no output schema, and no nested objects, the description is complete. It covers all necessary aspects: input requirements, default values, return fields, edge cases (thin legs, forced directional risk), and usage context. No gaps are evident.

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 description coverage, the tool description adds significant meaning beyond the schema. It explains the difference in size_usd interpretation between single-market (max spend/target proceeds) and basket (settlement notional), and clarifies default values and clamping. The descriptions for side and market/event are also enriched with mode-specific details.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and specifies the required parameters, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidelines are provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it, such as partial basket fills converting an arb into an unhedged directional position.

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 greatly expands on the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing compatibility_warning, temporal_alignment, and skipped_cross_type/subtype fields. It explains what these mean for the validity of spreads, providing essential behavioral context beyond structured data.

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

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

The description is well-structured with clear sections and front-loaded purpose. However, it is verbose, especially the detailed explanation of compatibility_warning scenarios, which could be more concise.

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

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

Given the complexity (3 parameters, no output schema), the description covers purpose, modes, response structure, safety fields, and limitations. It explains return values (raw probabilities, spreads, compatibility warnings) and edge cases, making it fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about the two modes and override behavior, but the schema descriptions themselves already list the macro shortcuts. The added value is modest, not transformative.

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 ('Cross-venue spread'), resource (Kalshi and Polymarket), and scope ('for the same resolving question'). It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue comparison rather than single-venue arbitrage.

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

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

The description explicitly explains two modes (topic and explicit) and warns that most pre-mapped topics return compatibility warnings, guiding when not to rely on it. However, it does not explicitly compare to alternatives or state when to use other tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by explaining the query syntax, return types (attribute rows and geometry), and parameter defaults, which goes beyond the annotations.

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

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

The description is two sentences: the first states the core function and parameters, the second gives a practical sample query. Every sentence is necessary and no words are wasted, achieving maximum conciseness.

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

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

Though there is no output schema, the description mentions return types ('attribute rows (and geometry)'), which is sufficient for a query tool. It could be more precise about the response format, but it adequately informs the agent about 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?

With 100% schema coverage, the schema describes all parameters. The description adds value by describing them as 'SQL-like', providing examples for `where`, `out_fields`, and `order_by`, and clarifying defaults (`1=1` and `*`).

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 ('Query'), identifies the resource ('ArcGIS Feature Service / Map Service layer'), and clarifies the source ('from search_datasets'). It differentiates from siblings by specifying SQL-like parameters and returning attribute rows and geometry.

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

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

The description provides a concrete usage example ('where="1=1" + out_fields="*"') and implies the tool is for querying layers found via search_datasets. It does not explicitly state when not to use it, 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 indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining scoping (user identifier) and pairing with remember/forget, which is consistent with 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 two sentences, front-loaded with the core purpose, and every sentence adds information. No wasted words.

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

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

For a simple retrieval tool with full annotations and schema coverage, the description provides sufficient context (scoping, pairing with other tools) and anticipates typical agent use cases.

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

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

Schema coverage for the single 'key' parameter is 100%. The description adds the usage nuance ('omit to list all keys') but does not provide additional meaning beyond the schema description.

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

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

The description clearly states the verb ('Retrieve' or 'list') and the resource ('value previously saved via remember'). It distinguishes itself from siblings like 'remember' and 'forget' by specifying the operation and its inverse.

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

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

The description explains when to use the tool (to look up stored context) and provides context for scoping. However, it does not explicitly state when not to use it or mention alternative tools among the 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) declare non-destructive, idempotent read behavior. The description adds critical context: mark_read:true flags events as read for subsequent calls, the feed is persisted, and returns specific fields. No contradictions with annotations.

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

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

The description is a single paragraph of five sentences, each adding distinct value: purpose and returns, filtering, mark_read behavior, polling suitability, and alternative access. No filler or redundancy. Front-loaded with core information.

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

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

Despite no output schema, the description explains return field structure (source, citation_uri, raw event payload), covers all parameters' usage, mentions persistence and polling, and provides an alternative access method. For a simple retrieval tool with optional params and safe annotations, this is complete.

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

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

Schema coverage is 100%, earning baseline 3. The description adds value by providing an example filter ("sec_8k"), explaining mark_read's effect ("flag returned events read so the next call only shows newer ones"), and noting that since expects an ISO timestamp. This enhances understanding beyond schema 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?

The description clearly states the tool's function: 'Pull fired events from your subscription feed. Returns the most recent alerts...' with specific verb and resource, and lists return fields (source, citation_uri, raw event payload). Although not explicitly distinguishing from sibling tools, the purpose is well-defined and unambiguous.

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

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

The description implies usage via polling ('Polls work fine') and mentions filtering options (type, since, mark_read). However, it does not explicitly state when to use this tool versus alternatives like list_subscriptions or subscribe, nor does it provide exclusions. The guidance is present but implicit.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) indicate safe, non-destructive reads. The description adds rich behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO (with note about PatentsView API sunset), and outputs structured changes grouped by source with citation URIs. No contradictions.

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

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

The description is compact (roughly 4 sentences) yet packed with information. It uses a front-loaded list of example queries, then explains the core functionality, fallbacks, and parameter usage. Every sentence contributes meaningfully, with no wasted words.

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

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

Given the tool's moderate complexity (multi-source query, time window parameter, fallback logic, output format), the description covers all necessary aspects: source behavior, parameter semantics, output structure (changes[] grouped by source, total_changes, citation URIs), and differentiation from similar tools. No output schema is needed, but the description adequately outlines 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?

Schema coverage is 100% with detailed descriptions. The description adds value by providing typical values for 'since' (e.g., '30d' for monitoring), explaining that 'type' currently only supports 'company', and clarifying that 'value' can be ticker or CIK. It reinforces and expands on the schema without being redundant.

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

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

The description opens with concrete example queries ('What's new with X', 'latest on Y'), then defines the tool as a change feed for a company in a time window via a single parallel call. It explicitly differentiates from sibling tool 'entity_profile' by stating when to use that instead.

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

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

The description provides numerous example use cases, explains when to use 'entity_profile' instead, details parameter expectations for 'since' (ISO date or relative shorthand with examples like '30d', '3m'), and describes fallback behavior between GDELT and GNews. No ambiguity remains.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds context: scoping by identifier and 24-hour retention for anonymous sessions. No contradictions. Additional details on expiration add value 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?

Description is four sentences; each sentence serves a distinct purpose: purpose, usage examples, storage details, related tools. No fluff. Well-structured and 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 a simple 2-param write tool with no output schema, the description covers purpose, usage, persistence, scoping, and sibling relationships. No gaps identified.

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

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

Schema has 100% description coverage with examples for both key and value. Description reiterates key-value pairing but does not add significant new meaning beyond 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?

Description clearly states the tool 'Save data' for reuse later. It specifies the resource (key-value pairs) and scope (across conversations/sessions). It distinguishes from siblings by explicitly mentioning recall and forget.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. Provides exclusions: 'so you don't have to look it up again' and alternatives: 'Pair with recall to retrieve later, forget to delete'. Also mentions persistence behavior for authenticated vs anonymous users.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: it returns specific fields per type, auto-disambiguates, and cascades through multiple endpoints. No contradictions.

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

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

The description is front-loaded with examples and purpose, then structured details. Each sentence serves a purpose; length is justified by the complexity of the tool. No fluff.

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

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

Given the tool has 2 parameters, full schema coverage, rich annotations, and no output schema, the description is complete. It explains return values for each type, mentions citation URIs, and notes internal efficiency. Adequate for agent invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the 'type' enum by explaining each option's scope and output, and the 'value' parameter with examples and accepted formats, adding meaning beyond the schema.

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

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

The description starts with concrete examples, clearly states the tool resolves names to canonical identifiers, specifies supported types (company, drug) with distinct outputs, and distinguishes from siblings by noting it replaces 2-3 manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternatives, but the context and sibling tools imply when it's inappropriate.

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

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

The description adds behavioral context beyond the annotations (readOnly, idempotent, openWorld) by revealing it calls ai_visibility_check internally, ranks results, and returns score, confidence, and signal density. This provides useful insight into tool behavior without contradicting annotations.

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

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

The description is three well-structured sentences, front-loaded with the core purpose, then mechanics, then a use case. Every sentence adds value, with no redundancy or unnecessary detail.

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 moderate complexity (4 parameters, no output schema), the description explains the process, return fields (score, confidence, signal density), and use case. It could mention the size limit (2-8 entities), but this is covered in the schema. Overall, it provides sufficient context for the agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds marginal value by giving an example for the context parameter ('B2B SaaS') and implying the role of entities ('your brand + N competitors'), 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('compare') and resource ('AI visibility'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different comparison type) by detailing the process of probing, ranking, and surfacing most/least recognized.

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 usage context ('competitive AI-marketing audits') and a concrete example question. While it doesn't explicitly state when not to use or list alternatives, it implies the tool is for multi-entity comparison, differentiating from single-entity probes.

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

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

Annotations already indicate readOnly, openWorld, idempotent, nondestructive. Description adds: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. 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 fairly long but each sentence adds value—purpose, alternatives, behavior, return structure. Front-loaded with purpose. Slight redundancy in listing return fields could be tighter.

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: summary block, per-advisory detail, links, alternative versions. Also covers error behavior and partial failures. Entirely adequate 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 describes both parameters fully (100% coverage). Description adds practical details: scoped packages accepted for package, and version defaults to latest. Adds modest value beyond schema.

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

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

The description explicitly states it's a composite check for npm packages, combining deps.dev and bundlephobia data. It clearly distinguishes from siblings by naming the specific sources and use case.

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

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

Provides explicit when-to-use: 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes ecosystem limitations: NPM only in v1, with fallback to deps.dev:version for others.

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 context beyond the annotations by detailing the return fields (name, summary, record_count, owner/org, url) and the intended follow-up action. Although annotations already indicate readOnlyHint and idempotentHint, the description enriches understanding of the output's utility.

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

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

Two sentences, front-loaded with the verb (Search) and resource (GIS datasets). Every sentence serves a purpose: stating the scope and linking to sibling tools. No wasted words.

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

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

For a search tool with 3 optional parameters and no output schema, the description is comprehensive. It specifies input examples, output fields, and how to chain with related tools, 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?

The description adds examples (e.g., 'parcels', 'crime') for the query parameter and explains the org_id parameter's purpose (override default org). Given 100% schema description coverage, the description provides useful supplementation without redundancy.

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 searches City of Novi GIS open geospatial datasets by keyword, with specific examples of dataset types (parcels, zoning, public works). It also differentiates from sibling tools by noting the returned URL should be passed to query_layer/layer_info.

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

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

The description explains what the tool does and explicitly tells the user to pass the returned URL to query_layer or layer_info for further data access. This provides clear context for when to use this tool vs. siblings. However, it does not explicitly state when not to use it, though 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, openWorldHint, idempotentHint, destructiveHint. The description adds significant detail: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation flag, and return of character offsets for verification. 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 fairly long but well-organized. First sentence front-loads the purpose, followed by detailed behavior. Could be slightly tighter but remains efficient and informative.

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

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

No output schema exists, but the description explains return type: top-N passages with character offsets and similarity scores. All 3 parameters are described with behavioral context, and the 200K char limit and truncation flag are noted. Covers all necessary aspects.

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

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

Schema coverage is 100% so baseline is 3. The description adds context: 'text' is from a fetched record (e.g., SEC 10-K), 'query' includes natural-language examples, and 'limit' defaults to 5. This enhances understanding beyond the schema.

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

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

The title and description clearly state it performs semantic search inside a fetched record. It specifies the verb 'search' and the resource 'inside a fetched record', and distinguishes itself from sibling tools by mentioning its companion tool 'ask_pipeworx_grounded'.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Also mentions pairing with 'ask_pipeworx_grounded', implying an alternative workflow and guiding the agent on proper usage context.

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

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

Describes creation behavior, return value, delivery mechanisms, constraints (sms cap, webhook signing, auto-disable). Adds context beyond annotations, which indicate mutation without destruction.

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 but dense. Every sentence adds value, but 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?

Covers main behavior, inputs, constraints. Lacks error handling details, but sufficient for a tool with no output schema.

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

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

Schema coverage is 100%. Description adds significant value with examples and constraints for each parameter and nested delivery object.

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

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

Clearly states it creates a subscription to a live-data event stream and returns a subscription id. Distinguishes from siblings 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?

Provides detailed guidance on supported types, parameters, and delivery channels. Mentions authentication requirement. Lacks explicit when-not-to-use or alternatives, but contextually clear.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive. Description adds that it returns category-bucketed example questions with tool shapes, drawn from a live catalog, which is behavioral context beyond annotations.

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

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

The description is detailed but well-organized, front-loading common queries. Could be slightly shorter, but every sentence adds value for an onboarding tool.

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

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

Given the simple nature (1 optional param, no output schema, read-only), the description fully covers purpose, usage, and expected output, leaving no gaps.

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

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

Schema coverage is 100% for the single optional parameter. Description reiterates the possible values and default behavior, matching the schema without adding new constraints.

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 identifies the tool as the onboarding entry point, listing specific use cases like 'What can I ask Pipeworx?' and 'give me ideas'. It distinguishes itself from sibling tools by stating its role in learning about the system and 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 advises to 'Use this FIRST' when unsure about capabilities and explains when to pass a topic vs. omit. Does not list when-not to use, but context implies it's not for direct data queries.

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

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

Adds value beyond annotations: explains that rows are deactivated (not deleted) and historical events remain via recent_alerts. Aligns with destructiveHint=false and idempotentHint=true. 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 efficient sentences with no redundancy. Front-loaded with action 'Cancel a subscription by id', each sentence adds essential information.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary aspects: action, ownership, deactivation behavior, and connection to historical data. Annotations handle idempotency and non-destructive nature.

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

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

Schema description coverage is 100%; the parameter 'id' is described in schema as 'Subscription id (uuid) returned by subscribe.' Description does not add new semantic detail beyond what schema provides, meeting the baseline.

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

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

The description clearly states 'Cancel a subscription by id' with explicit verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation and ownership enforcement.

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

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

Provides clear ownership constraint ('you can only cancel your own subscriptions'), but does not explicitly compare to alternatives or state when not to use. The context is sufficient given sibling list.

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

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

Description adds significant behavioral context beyond annotations: it reveals the underlying data sources (SEC EDGAR + XBRL), the return format (verdict types, structured form, actual value with citation, percent delta), and the efficiency gain. 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 front-loaded with trigger phrases and core purpose, then efficiently covers scope, return details, and benefits. Every sentence earns its place, though it could be slightly tightened.

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 return values (verdict types, citation, delta). It covers purpose, usage, sources, and efficiency. For a single-parameter tool with rich annotations, this is complete.

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

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

The schema description already provides 100% coverage for the single 'claim' parameter with an example. The tool description adds trigger phrases but no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description starts with explicit trigger phrases ('Is it true that…', 'fact check', etc.) and clearly states the tool's purpose: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims) and 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?

Clearly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and scopes to company-financial claims. It doesn't explicitly say when not to use, but the scope and efficient replacement of multiple calls provide clear context.

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