Arcgis Asheville

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals key behaviors: default model is Workers AI Llama-3.3-70b, Anthropic requires a BYO key passed directly, output includes per-model fields like score, confidence, signals, raw_response, and a combined view. 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 one paragraph but well-structured: it states the main action, default behavior, optional additions, and output format. It is informative without being verbose, though it could be slightly more structured for quick scanning.

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 essential aspects: entity, models, API key, context, and output format. Lacks mention of error handling or rate limits, but given the tool's simplicity and annotations, it is sufficiently complete 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%, and the description adds meaning: clarifies that 'models' is optional (defaults to workers-ai), '_apiKey' is only needed if 'anthropic' is in models and is passed through, and 'context' helps disambiguate. This enriches the agent's understanding beyond the schema definitions.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs for entity knowledge) and output (visibility 0-100 per model). It distinguishes from siblings by focusing on AI visibility scoring for brands/products, which is not covered by other tools like 'deep_research' or 'entity_profile'.

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

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

Provides explicit use cases (AI-marketing audits, brand checks, competitive monitoring) and explains when to provide an API key. Does not explicitly state when not to use or list alternatives, but the context signals and sibling list make the niche clear.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds that it routes to many tools, returns structured answer with citations, and covers many sources. 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?

Long but efficient; every sentence adds value. Front-loaded with key directive and examples. No wasted text relative to 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 broad scope and many siblings, description is complete: explains when to use, what it does, examples, comparisons, and return format (structured with citations). No gaps.

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

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

Schema coverage is 100% with aliases documented. Description does not add new meaning beyond schema, just mentions that it accepts natural language. 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?

Clearly states it is for asking factual questions about current or historical data, listing specific domains. Distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides when/not to use, and directs to alternatives for specific needs (hallucination-resistant, broad multi-part).

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 key behavioral traits beyond annotations: the two-step process (tool routing then extraction), the refusal mechanism with specific refusal reasons, and the return format. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description adds context about safety through refusal, which is consistent.

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

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

The description is front-loaded with the core purpose and usage, then provides detailed behavioral notes. It is somewhat verbose but every sentence adds unique information about refusal reasons, return format, and cost trade-offs. Could be slightly more concise, but remains clear and scannable.

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

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

The description fully compensates for the lack of an output schema by detailing the exact return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and explaining all possible refusal conditions. It also covers the extra LLM call cost and comparison with sibling, making the tool complete within its context.

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

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

The input schema has 100% description coverage with six parameters all aliases for 'question'. The description only reiterates that it accepts natural language. Since the schema is exhaustive, the description adds minimal semantic value, meeting the baseline expectation but not exceeding it.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with sibling 'ask_pipeworx' by noting it extracts answers only from tool results and costs an extra LLM call. The verb 'extracts' and resource 'answer from tool result' are precise, and the use cases are well-defined.

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

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

The description provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also tells when NOT to use it: 'prefer ask_pipeworx for casual lookups' and notes the extra cost trade-off.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context beyond annotations: fan-out logic per bet type, response shapes with specific fields, resolver contract including confidence levels and alternative markets, parent event extractor for partitions, news fallback mechanisms, safety short-circuits for low confidence or closed markets, illiquid spread handling, and cancellation rule parsing. No contradiction with annotations.

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

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

The description is very long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with purpose. However, it contains some redundancy and could be trimmed (e.g., repeated explanations of low-confidence paths). Every sentence adds value, but overall verbosity makes it less concise than ideal.

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

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

Given the tool's complexity (multiple fan-outs, response shapes, resolver logic, parent events, news fallbacks, safety mechanisms, cancellation rules) and lack of output schema, the description is highly complete. It covers all necessary aspects for correct invocation and interpretation, including edge cases like closed markets, wide spreads, and low-confidence matches.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: it explains that 'market' accepts a slug, URL, or question text; it defines 'depth' enum values ('quick' = 2-3 sources, 'thorough' = full fan-out) and default; it explains 'include_raw' default false and tradeoff (summary vs full payloads). This far exceeds the baseline 3 for full schema coverage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research/pull) and resource (Polymarket bet), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by being a general research tool. Examples of fan-outs for different bet types further clarify scope.

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

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

The description provides explicit usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples of when to use different fan-outs. However, it lacks explicit when-not-to-use instructions or direct comparisons to siblings, which would elevate it to a 5.

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

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

Annotations already indicate readOnly, idempotent, openWorld. Description adds behavioral details such as data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, and sorting of results. It does not mention potential errors or data availability, but overall provides good context.

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

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

The description is well-structured with front-loaded example queries that guide usage. It is somewhat long but each sentence contributes value; it could be slightly more concise without losing clarity.

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

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

For a comparison tool with two entity types and no output schema, the description covers inputs, data sources, and output characteristics (sorted, citation URIs). It does not detail exact output format, but is sufficient for an agent to understand expectations.

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 significantly enriches the schema by explaining what data each entity type pulls (e.g., revenue, net income, adverse events) and the format of values (tickers/CIKs vs drug names). Schema coverage is 100%, but the description adds valuable semantics.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs using specific verbs like 'compare', and distinguishes it from siblings by explicitly preferring it 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 provides clear context for when to use this tool (comparing entities) and explicitly prefers it over sequential lookups. However, it lacks explicit exclusions for when not to use it, e.g., for single entity 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant context: parallel decomposition, return format (findings with evidence, confidence, gaps), expected latency (15-60s), and behavior when topic is not in catalog (empty gaps).

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

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

The description is longer than average but every sentence adds value. It is front-loaded with critical prerequisites and alternatives, well-structured with clear sections. A slight trim could be possible, but overall effective.

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

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

Despite no output schema, the description fully explains the return format, behavior, prerequisites, and expected timing. It covers all necessary context for a complex tool, leaving no significant 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%. The description explains the depth parameter levels (quick=3, standard=5, thorough=8) and clarifies that the question parameter is for broad/multi-part queries, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, decomposing questions into facets and running parallel tool calls. It distinguishes itself from sibling tools like ask_pipeworx, which is for single lookups or current news.

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 provides when-to-use scenarios (broad/multi-part questions over structured data) and when-not-to (single lookup or breaking news). It also mentions account and tier requirements, guiding the agent to use ask_pipeworx as an alternative.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are 'ready to call directly' with curated examples, which provides useful 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?

Front-loaded with core purpose, then lists many domains which could be trimmed but provides useful examples. Structure is clear and effective, though slightly verbose.

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

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

Given the tool's complexity (6 params, no output schema), the description thoroughly covers what the tool does, what it returns, and when to use it. It is complete for effective 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 description coverage is 100%, so baseline 3. Description includes example queries but does not add significant meaning beyond what the schema provides for parameters.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains (SEC filings, financials, etc.), and explains it returns top-N relevant tools with schemas. This is specific and distinguishes it from sibling tools which are mostly specific domain tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear guidance. Does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Annotations already show read-only, idempotent, open-world behavior. Description adds significant context: it fans out across multiple sources, returns specific fields, mentions fallback mechanisms (GDELT→GNews), and notes deprecation (USPTO API). 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 comprehensive but slightly verbose. However, it is front-loaded with example queries and structured logically. Every sentence adds value, but could be tightened slightly without losing information.

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

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

Given the tool's complexity (multiple sources, fallbacks, deprecation), the description covers most key aspects: data sources, returned fields, behavior with different inputs. No output schema, but the description of returns is adequate. Lacks explicit error handling or pagination details, but acceptable for a profile tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds value by explaining the 'type' parameter is currently limited to 'company', 'value' can be ticker or zero-padded CIK, and names are not supported. Examples ('AAPL', '0000320193') enhance understanding beyond schema.

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

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

Description clearly states the tool provides a full cross-source profile of US public companies, lists numerous example queries, and distinguishes itself by recommending preference over chaining single-source lookups. Sibling tools like resolve_entity and search_within are explicitly differentiated.

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 (holistic view of a company) and when not to use (names not supported, use resolve_entity first). Also notes the patent API sunset and soft-fail behavior, guiding the agent on expected outcomes.

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 destructiveHint: true and idempotentHint: true. The description adds value by explaining the purpose (clearing stale or sensitive data), which goes beyond the annotations. No contradiction.

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

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

The description is two sentences: first states the core action, second provides usage guidance and sibling context. No wasted words, front-loaded with purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage scenarios, and sibling relationships. Annotations handle behavioral traits. The description 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?

There is only one parameter (key) with schema description 'Memory key to delete.' The tool description does not add further detail beyond the schema, but schema coverage is 100%, so baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory), and distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with remember and recall, but lacks explicit 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 declare readOnlyHint=true and idempotentHint=true, which the description aligns with by stating it 'fetches the page' (read) and emits a file. The description adds valuable behavioral context (extracts title/description/key links, emits standard markdown, output ready to drop at site-root). No contradiction.

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

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

The description is concise with three focused sentences, front-loaded with the primary purpose and output format. Every sentence adds value, no redundancy.

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

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

Despite no output schema, the description explains the output format ('standard llms.txt markdown', 'single text blob ready to drop at site-root'). For a simple tool with 2 parameters and clear annotations, this is complete and sufficient.

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

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

Schema description coverage is 100% with clear parameter descriptions for 'url' and 'max_links'. The description does not add additional meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt). It distinguishes from siblings like scan_competitor_ai_presence by focusing on llms.txt generation for AI indexing.

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

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

The description lists three explicit use cases (indexing a client's site, drafting for own project, auditing competitor), providing clear context for when to use. However, it does not explicitly state when not to use or mention alternative tools by name.

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's safety profile is clear. The description adds what the tool returns, which is consistent and provides additional behavioral context. 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?

Single sentence with clear structure, front-loading the verb and resource. Every word adds value, and there is no redundancy.

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

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

Given a single parameter, no output schema, and comprehensive annotations, the description covers all necessary context: what the tool does, what it returns, and the nature of the input. 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?

Input schema has 100% coverage with a description for the 'url' parameter. The description adds a concrete example of the URL format, which is helpful but not extensive; baseline is 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 verb 'Get', the resource 'ArcGIS Feature/Map Service layer's schema', and specifies the returned information: fields, geometry type, record count, and capabilities. This distinguishes it from siblings like 'query_layer' which likely queries data.

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

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

No explicit guidance on when to use this tool versus alternatives such as 'query_layer' for data queries or 'search_datasets' for dataset searches. The description does not provide context for exclusion or indication of typical use cases.

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

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

Annotations already cover read-only and idempotent behavior. The description adds the return format (list of fields), which provides useful context beyond annotations but does not disclose any additional 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?

Two short sentences with no redundant information. Purpose, return fields, and usage are all front-loaded efficiently.

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 listing tool with one optional parameter and no output schema, the description covers purpose, return structure, and usage scenario completely.

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

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

Schema coverage is 100% for the single optional parameter 'include_inactive', so the description need not add more. It does not mention the parameter, but the schema already suffices.

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 the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from siblings like subscribe and unsubscribe by focusing on listing.

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

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

Explicit guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for when to use the tool, implying alternatives are subscribe/unsubscribe.

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

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

Discloses rate limit (5 per day), free usage, and that it doesn't count against quota; annotations are all false, so 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?

Three well-structured sentences, front-loaded with purpose, no redundant information.

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

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

Covers purpose, usage, constraints, and formatting guidance; no output schema needed for acknowledgment.

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

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

Adds meaning to type enum values and provides usage guidance for message (be specific, length limit). Context is clarified but schema already covers properties.

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 is for sending feedback about Pipeworx being broken, missing, or needing existence. Distinguishes from siblings as the only feedback tool.

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

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

Explicitly lists when to use each feedback type (bug, feature/data_gap, praise) and advises against pasting end-user prompts.

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 declaring it safe (readOnlyHint, idempotentHint, destructiveHint=false), the description adds significant behavioral details: data source (CF analytics-engine), privacy (no PII), output format (pack, tool, count), and caching policy (5min-1h). This fully characterizes the tool's behavior.

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

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

The description is front-loaded with the main action, then lists use cases and details. It is slightly verbose but every sentence contributes. Structured as a clear paragraph with a bullet-like list, easy to parse.

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

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

Given a simple optional parameter, thorough annotations, and no output schema, the description covers all essential aspects: purpose, use cases, data source, privacy, caching. It could mention the output format more explicitly (e.g., sorted list), but overall it is complete enough for selection and 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?

The input schema has 100% coverage and already describes the parameter. The description adds value by stating the default ('24h') and explaining the trade-off ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which aids in selection.

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 from other AI agents on Pipeworx over a recent window. This specific verb+resource combination is distinct from sibling tools like discover_tools (which lists tools available) and ask_pipeworx (which answers queries).

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and explains how window parameter choices affect results. It does not explicitly mention when not to use, but the clarity of use cases compensates.

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 read-only, open-world, idempotent, non-destructive, so the tool is safe. Description adds critical behavioral details: fill check against live CLOB depth, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), all beyond what annotations provide.

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

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

The description is detailed and well-structured with labeled sections, but slightly verbose. Every sentence adds value, but could be more terse without losing clarity.

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

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

Given no output schema, the description fully explains the return structure (opportunities[], partition_check, fill_check) and edge cases (filtered slugs, low similarity). No gaps for agent decision-making.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant context: explains event slug format, topic as seed question, and the implications of each mode. It enhances understanding beyond the schema alone.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes modes (no args, event, topic) and refers to sibling tools like polymarket_fill_risk for custom sizing, ensuring the agent can differentiate.

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 recommends event mode for specific markets, explains when to use topic mode, and warns against trading when realizable_edge_pp ≤ 0. Also mentions polymarket_fill_risk for custom sizing, providing clear 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?

The description goes far beyond annotations, disclosing detailed behavioral traits: model families, caching behavior (1h KV-level cache keyed on all knobs), response structure with diagnostics, and edge metrics (edge_pp_net, kelly_fraction, etc.). It does not contradict any annotations.

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

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

The description is well-organized with clear segmentation but is overly verbose, containing detailed algorithmic explanations that could be streamlined. It includes extensive examples and internal logic that, while informative, may overwhelm an agent tasked with simple invocation.

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

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

Despite no output schema, the description thoroughly covers response structure (by_segment, fed_candidates, diagnostics), caching, and the meaning of all returned fields. Given the tool's complexity (9 parameters, 3 segments, multiple filters), this is complete and leaves no ambiguity.

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 all parameters have descriptions. The tool description adds marginal value by explaining the role of some parameters in context (e.g., min_kelly filters small opportunities), but mostly repeats schema information. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes itself by detailing three specific response segments (model_driven, structural_arbitrage, concentrated_longshot) and provides concrete use cases like 'what should I bet on today', making it distinct from sibling tools.

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

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

The description provides clear context for when to use the tool (discovering opportunities without paging hundreds of markets) and includes actionable knobs like min_liquidity and max_spread_pp for filtering tradeable edges. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: data comes from daily snapshots, response includes tracked/expired/snapshot_dates, decay computed from daily closes, and limits (60-day TTL). No contradictions with annotations.

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

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

The description is well-structured with clear sections: purpose, args, response format, and limits. It is front-loaded with the core question, and every sentence adds value without redundancy.

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

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

Given the complexity of the tool (tracking edge persistence over time, decay, expired edges), the description is thorough. It covers the response structure in detail, including fields like trend, decay_pp_per_day, lifespan_days, and snapshot_dates, and explains limits and data gaps. The absence of an output schema is compensated by the detailed textual description.

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 defaults and clamps for 'days' (default 14, max 30) and explains window family meanings, providing additional guidance beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?' It distinguishes itself from the sibling 'polymarket_edges' by focusing on time-series analysis of edges rather than just current edges.

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

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

The description provides context on when to use this tool (to differentiate between fresh and old edges) and explains its data source and limits. However, it does not explicitly state when not to use it or directly compare to sibling tools like polymarket_edges, though the context implies it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and provides verdicts. It also explains the risk of partial fills in basket mode. 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 comprehensive but slightly verbose. It uses headings and bullet-like list for modes, making it scannable. Every sentence adds value, but could be tightened slightly without losing information.

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

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

Given the tool's complexity (two modes, no output schema), the description covers key return fields and behavior. It explains the verdict output, thin_legs, and forced_directional_risk. However, it doesn't enumerate all return fields in a structured list, but the prose description is sufficient for understanding.

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

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

Schema coverage is 100%, so description's addition of meaning beyond schema is assessed. The description explains size_usd differently for single-market (max spend/target proceeds) vs basket (settlement notional), and clarifies side defaults. This adds value beyond the schema descriptions, warranting above baseline 3.

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

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

The description clearly states the tool evaluates realizable vs theoretical edge against live CLOB order-book depth. It explicitly distinguishes between single-market and basket modes, providing specific use cases for each. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why, citing the risk of partial fills creating unhedged directional positions.

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) are complemented by thorough description of behavior: modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters). 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?

Well-organized with sections for modes, response, and safety fields. Front-loaded with the core concept. Slightly verbose in repeating warnings, but overall efficient for the complexity.

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

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

Given no output schema, the description thoroughly explains return values (leg-by-leg prices, top_spreads_pp, safety fields). Covers edge cases like non-equivalent bet shapes and temporal misalignment. Complete for a complex three-parameter tool.

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

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

Schema coverage is 100%, so parameters are fully described. The description adds value by explaining the topic mode (list of shortcuts) and explicit mode (overrides), plus examples. Doesn't add much beyond schema but provides practical context.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Differentiates from sibling tools like polymarket_arbitrage and compare_entities by focusing on this specific cross-venue comparison.

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

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

Provides explicit usage context: two modes (topic shortcuts and explicit pairings) and detailed conditions when the spread is meaningful vs. not (compatibility warnings). Lacks explicit alternatives, but the safety fields guide when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds that the tool queries a layer and returns attribute rows and geometry, providing sample query syntax. It discloses that limit defaults to 50, which is useful additional context beyond the annotations.

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

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

Three sentences cover purpose, parameters, and a usage example with no redundancy. Every sentence is essential and front-loaded with the core function.

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

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

For a tool with 6 parameters (1 required), clear annotations, and no output schema, the description succinctly explains the core functionality, parameter usage, and a sampling pattern. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving examples of valid values (e.g., SQL where clause like 'STATE = ''CA'' AND YEAR >= 2020', order_by like 'POP DESC') and explaining that out_fields='*' returns all fields. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature Service/Map Service layer by URL, listing key parameters (where, out_fields, order_by, limit, offset) and specifying it returns rows and geometry. It explicitly links to search_datasets, distinguishing it from that sibling tool.

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

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

The description provides concrete usage patterns, e.g., use where='1=1' and out_fields='*' to sample. It implicitly guides the agent on when to use this tool (after search_datasets). While it doesn't explicitly state when not to use it or name alternatives, the context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping details (anonymous IP, BYO key hash) and pairing with siblings, enhancing transparency beyond annotations.

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

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

Three concise sentences, no fluff. Purpose stated first, then usage guidance, then scope and companion tools. Highly efficient.

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

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

Simple tool with full annotations and schema coverage. Description covers purpose, usage, scoping, and relationships to siblings, making it complete for agent understanding.

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

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

Schema coverage is 100% and the description adds no new information about the 'key' parameter beyond what the schema already says ('omit to list all keys'). Baseline of 3 is appropriate.

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

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

Clearly states it retrieves a saved value or lists all keys if omitted. Distinguishes from siblings 'remember' (save) and 'forget' (delete) by contrasting the action.

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: to look up previously stored context without re-deriving. Provides examples and mentions scoping. Lacks explicit 'when not to use' but the intended usage is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond annotations: it explains the returned fields (source, citation_uri, raw payload) and the effect of mark_read (flagging events read so subsequent calls only show newer ones). This is sufficient for agents to understand the tool's behavior without needing to infer from schema alone.

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

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

The description is concise (4 sentences) and front-loaded with the main action. Every sentence adds value: first sentence states purpose, second details return data, third explains parameters, fourth gives usage tips. No redundant or vague phrases.

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

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

Despite having no output schema, the description thoroughly covers all five parameters (type, limit, since, mark_read, unread_only) and their effects. It explains the return format (source, citation_uri, raw payload) and provides polling guidance and an alternative access method. For a tool with no output schema, this is complete and sufficient for an agent to use 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 coverage is 100% with each parameter having a description. The description adds semantic value by elaborating on the effect of mark_read ('flag returned events read so the next call only shows newer ones') and clarifying the since parameter ('ISO timestamp'). While the schema already provides basic descriptions, the tool description deepens understanding, justifying a score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (fired events from subscription feed) and the action (pull). It distinguishes itself from siblings by describing what it returns (source, citation_uri, raw payload) and noting an alternative HTTP endpoint, indicating it's the programmatic access.

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 how to use the tool with optional filters (type, since, mark_read) and mentions that polling works fine. It also provides an alternative method (HTTP endpoint) for scripts/dashboards, giving context on when to use this tool vs. the direct URL. However, it does not explicitly compare to sibling tools that might have overlapping functionality (e.g., list_subscriptions), which would raise the score to 5.

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

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

Discloses fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior, soft-fail for USPTO, and return structure (changes[] grouped by source + total_changes + citation URIs). Annotations already indicate safe read, but description adds detailed 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 somewhat lengthy but well-structured: starts with usage examples, then explains data sources, then output format, then alternative tool. 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 complexity (multiple sources, fallback, no output schema), the description covers input, behavior, and return structure. Minor gaps: no mention of rate limits or error handling beyond fallback, 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 coverage is 100%, and description adds value with examples for `since` (ISO date or relative shorthand like '7d'), explains `value` accepts ticker or CIK, and clarifies `type` enum limitation.

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

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

The description clearly states the tool retrieves a change feed for a company (e.g., 'What's new with X') and distinguishes from sibling `entity_profile` by explicitly contrasting static profile vs. change feed.

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 examples (latest, updates, news) and explicitly says when NOT to use ('Use entity_profile instead when you want the static profile'). Also explains fallback logic between GDELT and GNews.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, which align. The description adds scoping by identifier, persistence details (authenticated vs. anonymous), and retention period (24 hours), going beyond annotations.

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

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

Four sentences, no waste. Purpose is front-loaded, and every sentence adds value (usage, scoping, pairing). Efficiently composed.

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

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

Given no output schema, the description explains storage behavior, scoping, retention, and pairing with recall/forget. No gaps for the agent to misuse.

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

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

Schema already covers both parameters with descriptions (100% coverage). The description adds meaningful examples of key values (e.g., 'subject_property', 'target_ticker'), enhancing understanding 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 clearly states the tool saves data for reuse across conversations/sessions, with specific examples (ticker, address, preference). It distinguishes from sibling tools recall and forget by naming them as counterparts.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and advises pairing with recall and forget. Provides clear context and alternatives without ambiguity.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups', which helps the agent understand internal complexity and efficiency.

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

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

The description is front-loaded with key examples and the directive to use first. It then uses structured bullet points for types. While slightly long, every sentence adds value and there is no redundancy.

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

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

Given 2 required parameters, no output schema, and high complexity (multiple lookups), the description is quite complete. It explains what each type returns, includes citation URIs, and mentions internal cascade. It lacks error handling notes but is sufficient for a lookup tool.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond enum descriptions: for 'type', it lists supported types and their return fields (ticker, CIK, RxCUI, etc.) with citation URIs. For 'value', it provides concrete examples (AAPL, ozempic). This greatly aids correct parameter usage.

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

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

The description clearly states it resolves names to canonical identifiers, with specific examples ('ticker', 'CIK', 'RxCUI') and explicitly mentions it is the first tool to use when needing an ID. It distinguishes itself from siblings by providing a primary lookup role.

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', giving clear when-to-use guidance. It does not explicitly state when not to use or list alternative tools, but the context is strong enough for an agent to decide.

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. Description adds that it probes each entity with ai_visibility_check, ranks by score, and treats first entity as subject. 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?

Four sentences, no wasted words. First sentence states purpose, second explains mechanism, third gives use case, fourth describes output. Well structured and front-loaded.

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

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

Covers workflow, output fields, and special treatment of first entity. No output schema but description compensates. Could mention potential rate limits or cost implications when using Anthropic API key, 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 coverage is 100%, but description adds usage guidance for models ('Omit for just workers-ai') and _apiKey ('only if anthropic in models'). For entities, explains first entry is subject. Adds value beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities using ai_visibility_check, ranks them, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (different comparison).

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

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

Explicitly positioned for competitive AI-marketing audits with a clear example ('does Claude know about us as well as our competitors?'). Implicitly distinguishes from single-probe tool. Lacks explicit when-not-to-use but context 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?

Beyond annotations (readOnly, idempotent, destructive false), the description discloses partial failure degradation, bundlephobia latency (5-30s first measurement), and that sources_failed will list timeouts. Full context for an agent.

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

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

Four sentences pack purpose, use cases, ecosystem scope, and partial failure handling. Front-loaded and every sentence adds value.

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

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

Despite no output schema, the description details return fields (summary block, advisories, links, alternatives) and error behavior. Completely covers what an agent needs to know.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds no new semantic meaning beyond the schema, which is already clear. Baseline 3 is appropriate.

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

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

The description clearly states this is a composite check for npm packages covering license, advisories, bundle size, etc. It distinguishes from sibling tools like 'deepl_research' or 'bet_research' by being specific to npm dependency evaluation.

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: for safety/popularity/size questions or cost of adding a package. Also states limitations: NPM only, other ecosystems map to deps.dev directly. No alternatives listed in siblings, but this is complete.

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 the tool is read-only, idempotent, and non-destructive. The description adds transparency by detailing what is returned (name, summary, record_count, owner/org, Feature Service URL) and how to use the output, providing valuable behavioral context beyond the annotations.

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

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

The description is very concise, consisting of two sentences that front-load the purpose and scope, then detail the return format and usage suggestion. Every sentence earns its place with no redundancy.

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

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

Despite lacking an output schema, the description fully explains what the tool returns and how to use the results with sibling tools. It covers all necessary information for an agent to effectively use the tool, including the search by keyword, optional parameters, and integration with query_layer/layer_info.

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

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

Schema description coverage is 100%, so each parameter is already described in the input schema. The description does not add additional parameter-level semantics, meriting a 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 searches City of Asheville GIS open geospatial datasets by keyword, specifying the resource and action. It distinguishes from siblings like query_layer and layer_info by noting that the returned URL should be passed to those tools.

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

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

The description explains the use case: searching datasets by keyword, and provides a clear next step (pass URL to query_layer/layer_info). It does not explicitly state when not to use this tool, but the context is sufficient for correct 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, and non-destructive behavior. The description adds critical details: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K chars with truncation flag), and that it returns offsets and similarity scores. No contradictions.

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

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

The description is a single dense paragraph, front-loaded with the core purpose. Every sentence adds value: usage guidance, pairing advice, technical details, and limits. 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 no output schema, the description adequately covers return values (passages with offsets and scores), technical constraints, and use cases. It lacks an example output but is otherwise 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 each parameter already has a clear description. The description adds context about use cases and the embedding approach, but doesn't significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It provides concrete examples (SEC 10-K, article) and distinguishes itself from siblings by specifying when to use it (record too large for prompt) and how it pairs with 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?

The description explicitly advises using this tool when 'the record is too big to cram into the prompt' and pairs it with ask_pipeworx_grounded. It explains the workflow: fetch then search. While it doesn't list alternatives, the context is clear and practical.

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

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

The description adds significant behavioral context beyond annotations: it mentions return value (subscription id), delivery channel limitations (10/day SMS cap, webhook auto-disable after 10 failures), and verification requirements. No contradictions with annotations; idempotentHint: true is consistent as the tool could be idempotent with same parameters.

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

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

The description is front-loaded with the core purpose and is well-structured, but it is lengthy. Every sentence adds value given the tool's complexity, but it 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?

The description covers most aspects: return value, supported types, parameter details, delivery channels. It lacks explicit error handling or response format beyond the subscription id. Given the absence of an output schema, the description compensates well but could be more complete.

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

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

With 100% schema description coverage, the description explains each parameter in depth with concrete examples (e.g., sec_8k items codes, polymarket_edge topics). It adds meaning beyond the schema by providing usage patterns and required combinations.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It explicitly lists supported types and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use this tool, including prerequisites (Pipeworx OAuth account) and type-specific parameters. It hints at alternatives like recent_alerts for pull retrieval. However, it does not explicitly state when not to use this tool or compare against other subscription-related 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, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds behavioral details: returns category-bucketed example questions, drawn from live catalog, can be called without arguments or with a topic. No contradictions.

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

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

The description is a single, well-organized paragraph that front-loads the main purpose. It is informative without being verbose, though it could be slightly more concise by grouping related details.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers what the tool does, how to use it, when to use it, and what to expect. It is complete and leaves no ambiguity.

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 describes the optional 'topic' parameter. The description adds meaning by listing example values ('finance', 'pharma', 'betting') and explaining the effect (focus on a specific area). Since schema coverage is 100%, baseline is 3, but the enrichment justifies a 4.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns example questions with tool+argument shapes from the live catalog. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by explicitly saying to use it first when unaware of what Pipeworx can do.

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

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

The description provides explicit guidance on when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and explains how to use it with optional topic filter. It also points to alternatives (meta-tools) for after onboarding.

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 beyond annotations by clarifying that the row is deactivated, not deleted, and that historical events remain accessible via 'recent_alerts'. This adds valuable behavioral context that annotations alone do not provide.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no extraneous information. Every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, behavioral outcome (deactivation), and side effects (historical events stay). It lacks details on return values or error handling, but is largely complete for the tool's complexity.

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

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

The input schema already fully describes the 'id' parameter (subscription uuid). The description does not add any additional meaning beyond what the schema provides, meeting the baseline for 100% coverage.

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 'Cancel a subscription by id.' This clearly identifies the verb-resource pair and differentiates from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description includes the ownership constraint ('you can only cancel your own subscriptions'), providing clear context on when the tool is applicable. However, it does not explicitly contrast with alternative tools like 'unsubscribe_all' or mention error conditions (e.g., invalid id), so it lacks full usage 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?

Adds significant context beyond annotations: describes return values (verdict, citation, delta), scope limitations, and that it replaces multiple steps. Annotations already declare read-only and idempotent, and description aligns without contradiction.

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

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

Description is fairly concise given the amount of information; front-loads with query examples. Could be slightly tighter, but every sentence contributes value.

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

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

For a single-parameter tool with no output schema but rich annotations, the description is thorough: explains scope, output structure, and rationale. Minor gap: no mention of handling out-of-scope claims.

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

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

Schema covers the single parameter 'claim' with description, but the tool description adds concrete examples of valid claim formats, enhancing understanding beyond schema alone.

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

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

Description clearly states the tool validates natural-language claims against authoritative sources, with specific examples of query patterns. It distinguishes itself from siblings 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?

Explicitly tells when to use (fact-checking user claims) and notes scope (v1 supports company-financial claims via SEC EDGAR + XBRL). Lacks explicit when-not-to-use or contrast with all siblings, but sufficient for correct selection.

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