Arcgis Johnsoncity

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds value by disclosing the default free model, the need for an Anthropic API key for that model, cost implications, and the return structure (score, confidence, signals, raw_response). 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 concise (5 sentences), front-loads the core action and output, and includes necessary details without redundancy. Every sentence adds value.

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

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

Given the tool's complexity (4 params, no output schema), the description is complete. It covers purpose, parameters, models, costs, return format, and use cases. Annotations provide the safety profile, so no gaps remain.

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

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

Schema coverage is 100%, and the description adds context beyond schema: examples for 'entity', clarification that 'models' array can be omitted for default, that '_apiKey' is only needed if 'anthropic' is in models, and a disambiguating example for 'context'. This fully compensates for any ambiguity in the schema.

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

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

The description uses specific verbs ('probe', 'score') and identifies the resource ('LLMs knowledge about an entity'). It clearly distinguishes the tool's purpose from siblings like 'deep_research' or 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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 states it's 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring', providing clear use cases. However, it does not explicitly contrast with similar sibling tools or state when not to use, leaving some 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. Description adds that the tool returns structured answers with citation URIs, works on all tiers, and makes one fast call. No contradictions.

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

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

The description is lengthy but well-structured, starting with the key directive and then elaborating. Every sentence adds value, though some could be tightened. The use of examples and sections is 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?

Fully covers the tool's role as a federated query system, explains sources, citations, and fallback paths. Given the complexity (5008 tools, 1318 sources) and no output schema, the description provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases and natural language input but adds little semantic beyond the schema's property descriptions. Examples provide some context.

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

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

The description clearly states the tool routes questions to a large set of verified sources for structured, cited answers. It uses specific verb+resource language ('PREFER OVER WEB SEARCH') and differentiates 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?

Provides explicit when-to-use guidance (factual questions, specific query patterns), when-not-to-use (hallucination resistance, broad/multi-part questions), and explicitly names alternatives (ask_pipeworx_grounded, deep_research, web search). Includes concrete examples.

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 as true, and destructiveHint as false. The description adds behavioral context: it is a full working router with experimental routing improvements, and explains the source-preference ranking mechanism. No contradictions with annotations.

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

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

The description is relatively long but every sentence adds value, starting with purpose and then detailing experimental features. It could be slightly more concise, but it is 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?

Given the complexity (beta with experimental routing), annotations, and lack of output schema, the description covers key aspects: identity, difference from stable, source-preference feature, and that it is a working router. It is sufficiently complete for an agent to decide to use it.

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

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

Input schema has 6 parameters (all aliases for 'question') with 100% schema description coverage. The description states 'same arguments' as ask_pipeworx but does not add new semantic meaning beyond what the schema provides. 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 it is a beta version of ask_pipeworx, a universal router with 5,008 tools, identical arguments and response shape. It specifically distinguishes itself from siblings by naming the stable router and other variants, and explains the experimental source-preference feature.

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 advises using this tool when wanting the newest routing with candidate improvements, and compares it to the stable router. It implies when to use (for experimental edge) but does not explicitly state when not to use or list alternatives beyond the stable version.

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. The description adds substantial behavioral context: the tool picks the right tool, fetches data, extracts answer only from result, returns evidence and confidence, and explains refusal scenarios. No contradiction.

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

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

The description is moderately long but well-structured, with a clear flow: purpose, mechanism, return format, use cases, and trade-off with sibling. Every sentence serves a purpose, though it could be slightly tightened.

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

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

Given the tool's complexity (tool selection, grounding, multiple refusal reasons) and lack of output schema, the description fully explains the return format, behavior, and when to use. It covers all necessary context 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 description coverage is 100%, so baseline is 3. The description adds that the question should be 'natural language' and lists aliases, but this adds minimal value beyond the schema's existing descriptions. The parameter meaning is already clear from 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 identifies this tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by noting it extracts answers only from tool results, preventing invention. The verb 'extracts' and resource 'answer from tool result' are specific.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on... Prefer ask_pipeworx for casual lookups.' Also lists refusal reasons, helping the agent decide when this tool is appropriate.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns fully. It details fan-out behavior, response shapes, resolver contract, parent_event extraction, news fallback, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and resolution-rule risk. 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 lengthy but front-loaded with the main purpose. Every sentence adds value, covering many details. It could be slightly more concise, but given the tool's complexity, the density is appropriate. 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?

Despite lacking an output schema, the description thoroughly documents the response structure (result.market, result.analysis, result.evidence, etc.) and handles numerous edge cases (low confidence, closed markets, illiquid spreads, cancellation rules). It is exceptionally complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant value: examples for 'market' (slug, URL, question text), explains 'depth' (quick vs thorough), and details 'include_raw' (response size trade-offs). This goes well beyond the bare schema.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output components (evidence packet, market-vs-model comparison). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a comprehensive single-bet research 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 explicitly states use cases: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It also covers when to inspect specific fields and mentions short-circuit conditions. However, it does not explicitly name alternative sibling tools or provide direct 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 set readOnly, openWorld, idempotent, not destructive. The description adds rich behavioral details: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, citation URIs, and efficiency gains. 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 front-loaded with example queries and every sentence adds value. Slightly longer than necessary but efficient given the context.

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

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

No output schema, but description mentions 'paired data + pipeworx:// citation URIs', which is sufficiently clear. Covers all essential aspects for a 2-param array 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 covers both parameters fully (100% coverage). Description further enriches with examples, value ranges (2-5), and specifics of what each entity type retrieves (e.g., 'LATEST 10-K revenue').

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, with specific example queries. It distinguishes from sibling tools like 'entity_profile' by emphasizing parallel lookups.

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

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

Explicitly advises preferring over sequential single-pack lookups and provides example triggers. However, it doesn't explicitly exclude cases like comparing more than 5 entities, though the max is defined in the schema.

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

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

Description adds substantial context beyond annotations: account requirement, depth behavior (gap recovery, contradictions, iterative hops), time expectations, output structure (gaps[], contradictions[], hop field, citation_uri), excerpting behavior, and never invents answers. No contradiction with annotations.

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

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

The description is quite long (multiple paragraphs) but front-loads the critical account requirement and usage guidance. Every sentence provides value, though some detail (e.g., exact numbers of sources/tools) could be trimmed without losing clarity. Still, it's well-structured.

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

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

Despite having only 2 parameters and no output schema, the description fully explains the tool's complex behavior (parallel decomposition, multiple depth modes, output packet structure, citation formatting, limitations) and provides precise alternatives. Nothing essential is missing.

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 by explaining depth levels (quick=3 facets, standard=5+gap recovery, thorough=8+lead chasing) and advising that broad multi-part questions are encouraged for the question parameter, going well beyond schema descriptions.

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

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

The description clearly states 'Grounded multi-source research' across structured data sources, and specifically distinguishes from siblings like ask_pipeworx for single lookups or breaking news, leaving no ambiguity about its purpose.

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

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

Explicitly tells when to use this tool (broad/multi-part structured data questions) and when not to (single lookups, breaking news), names the alternative (ask_pipeworx), and even provides account tier details for depth options.

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. The description adds value by detailing that it returns top-N relevant tools with full input schemas and curated examples, ready to call directly. No contradictions.

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

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

The description is concise, with every sentence adding value. It is front-loaded with the purpose, then details usage and output. No wasted words.

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

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

Given the tool has 6 parameters but no output schema, the description adequately covers purpose, usage, and output format (top-N results with schemas). It is complete for an agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema, though it provides example queries and clarifies multiple aliases. This meets the baseline without significant enhancement.

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

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

The description states 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes itself from siblings by mentioning it returns schemas and curated examples, aiding tool selection.

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 context for when to use. It also lists many example domains, though it lacks explicit when-not or alternative sibling 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?

Discloses parallel execution, patent soft-fail, GDELT→GNews fallback, number of filings (up to 5), fundamentals order (LATEST 10-K, sorted), and output format including URIs. Annotations already indicate safe/idempotent, but description adds rich 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?

The description is dense but well-organized starting with example queries, then sources, then return fields. Slightly long but every sentence is informative. Could benefit from line breaks for readability, but is appropriately thorough.

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 complex tool with no output schema, the description covers all key aspects: supported type, input format, sources, return fields with specifics (count, ordering, URIs, fallbacks), and known limitations like patent sunset. Leaves no major gaps for an agent to understand behavior.

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

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

Schema coverage is 100% with descriptions, but the description adds value by emphasizing zero-padded CIK format and explicit disallowance of names. This goes beyond the schema's enum and string description.

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

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

The description explicitly states it produces a 'full cross-source profile of a US public company in ONE parallel call' and lists all sources and returned fields. It differentiates from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and clarifies input types with examples.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining' for holistic views, fallback for names via resolve_entity, notes patent sunset and soft-fail, and specifies that only ticker or CIK are accepted. This clearly tells when and 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?

The description's 'Delete' directly conveys destructive behavior, which aligns with the destructiveHint annotation. It adds context about clearing sensitive data, which goes beyond annotations. However, it does not add significant behavioral details beyond what the annotations already convey.

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 extremely concise with two sentences, each serving a distinct purpose: defining the action and providing usage context. It is front-loaded with the core 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 required parameter and full schema coverage, the description is complete. It explains the action, when to use it, and how it relates to sibling tools. No output schema is needed for a typical deletion operation.

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

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

The schema has 100% coverage with a clear description for the 'key' parameter. The tool description does not add further meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by explicitly mentioning them.

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

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

The description provides concrete scenarios for when to use the tool (stale context, task done, clear sensitive data) and pairs it with related tools, offering excellent guidance on when to use versus alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds that it fetches the page and extracts title/description/key links, which is helpful. However, it does not disclose potential issues like rate limits, size constraints, or error handling for invalid URLs.

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 purpose. 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 the tool's simplicity (2 parameters, no output schema), the description covers purpose, usage, behavior, and output format. It lacks error handling details but is sufficient for most use cases.

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

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

Schema coverage is 100%, so baseline 3. The description adds slight context for the 'url' parameter by giving examples, but does not mention the 'max_links' parameter, which is documented in the schema. No significant value added beyond schema.

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

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

The description clearly states the tool generates an llms.txt file for a URL for AI crawlers, specifies the output format, and lists concrete use cases. It distinguishes itself from siblings by focusing on a specific task.

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

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

The description provides explicit use cases (client site indexing, own project drafting, competitor auditing) that guide when to use. It does not mention when not to use but is adequate given sibling diversity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by listing the specific information returned (fields, geometry type, record count, capabilities), filling gaps not covered by annotations.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and output. It is concise and front-loaded, though minor restructuring could improve readability.

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

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

Given one required parameter and no output schema, the description adequately explains what is returned. It does not cover error cases (e.g., invalid URL), but for a simple retrieval tool, the completeness is satisfactory.

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% for the single 'url' parameter. The description's 'by url' adds minimal value as the schema already describes the URL. No further parameter semantics are provided beyond the schema.

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

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

The description clearly states it retrieves schema details (fields, geometry type, record count, capabilities) for an ArcGIS Feature/Map Service layer by URL. It uses a specific verb 'Get' and resource 'schema', distinguishing it from siblings like 'query_layer' which likely queries actual features.

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

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

The description implies usage for obtaining layer schema but does not provide explicit guidance on when to use this tool versus alternatives. Sibling 'query_layer' exists but no exclusion or comparison is given.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds return fields and parameter behavior, but does not disclose anything beyond that. No contradiction.

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

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

Two sentences with no fluff. First sentence defines the tool, second provides usage context. Every word earns its place.

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

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

For a simple listing tool with rich annotations and a single parameter, the description provides sufficient context about return fields and usage intent. No output schema needed.

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

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

Schema description covers 100% of the single parameter. The tool description does not add additional meaning beyond the schema's description of 'include_inactive'.

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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context and implying alternatives.

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

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

Since all annotations are false, the description bears full responsibility for behavioral disclosure. It reveals rate limits (5 per identifier per day), quota exemption, and the impact on roadmap, providing key behavior beyond what annotations offer.

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?

6 sentences with no wasted words. Front-loaded main purpose, then bullet-like usage scenarios, followed by rate limit info. Every sentence earns its place.

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

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

Together with the schema, the description covers purpose, parameter details, usage guidelines, rate limits, and what to avoid. No output schema is needed for a feedback tool, and the description is fully adequate for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, baseline is 3. The description adds extra guidance on message format (specificity, length, character limit) and explains enum values beyond the schema, enhancing parameter 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's purpose: sending feedback about broken, missing, or needed features to the Pipeworx team. It specifies distinct categories (bug, feature, data_gap, praise) and distinguishes from sibling tools, none of which are for feedback.

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 describes when to use the tool (bug, feature/data_gap, praise) and provides guidance on what to include ('describe in terms of Pipeworx tools/packs, don't paste user prompt'). Also mentions rate limit and that it's free and doesn't count against quota, giving clear context for 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?

Beyond the annotations (readOnly, idempotent, not destructive), the description adds valuable context: data is self-aggregated from CF analytics-engine, contains no PII, and is cached 5min-1h. This provides a clear behavioral understanding.

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

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

The description is concise (5 sentences), front-loaded with the main purpose, and uses bullet points for use cases. Every sentence adds value with no redundancies.

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

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

Given the simple nature of the tool (one optional parameter, no output schema), the description adequately explains what is returned (top tools, packs, call volume) and how it works. Annotations further cover safety and side effects.

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

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

The schema covers the parameter fully (enum with descriptions). The description adds further guidance on window choice ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which improves 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 returns 'top tools, top packs, and total call volume' over a time window. It uses specific verbs ('returns') and distinguishes from siblings by focusing on aggregate social proof rather than individual 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 choice, seeing use case alignment) which guide when to use this tool. While it doesn't explicitly say when not to use, the use cases serve as effective guidelines.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds rich behavioral context: monotonicity checks, Jaccard similarity filter, placeholder filter, fill check with realizable edge. 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?

Description is lengthy but packed with valuable information. It is front-loaded with purpose but could be more structured (e.g., bullet points for modes). Still clear and comprehensive.

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 multiple modes, fill check, filters, and no output schema, the description covers all necessary aspects: input modes, behavior, return fields, and cross-tool reference.

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 meaning beyond schema by explaining the modes, accepted inputs (slugs, URLs), and how the tool uses each parameter.

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 three distinct modes (trending_scan, event, topic) with specific details on what each does.

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

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

Explicit guidance on when to call with no args, pass event, or pass topic. Provides recommendations (event recommended for specific market). Does not explicitly state when not to use, but 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?

The description adds significant behavioral context beyond annotations, such as caching ('Cached 1h at the KV level'), detailed output structure with diagnostics explaining why segments might be empty, and the logic behind model families. It aligns with readOnlyHint, openWorldHint, and idempotentHint.

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 for model families, knobs, and response structure. However, it is verbose with excessive details (e.g., exact filter thresholds) that could be condensed without losing essential information.

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

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

Given the complexity and lack of output schema, the description thoroughly explains the output structure (by_segment, fed_candidates, diagnostics) and field meanings (edge_pp_net, kelly_fraction, etc.). It covers all necessary context for an agent to correctly use the tool.

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

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

All 9 parameters are described in the schema, and the tool description adds extra context and rationale (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly clarifies its difference from min_kelly). This adds value 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for a specific use case ('what should I bet on today') and distinguishes itself from sibling tools by focusing on disagreement with Pipeworx data.

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

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

The description provides extensive guidance on when to use the tool, including the three opportunity segments (model-driven, structural arbitrage, concentrated longshots) and the tradeable-edge knobs. However, it does not explicitly state when not to use it or compare to 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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds critical behavioral details: it reads daily snapshot closes, computes trends (new/widening/stable/decaying), notes decay is on absolute edge_pp_net, and explains limitations (60-day TTL, cache-miss snapshots). 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 dense and front-loaded with the core question. Every sentence contributes information, though it is longer than strictly necessary. The structure could be slightly more organized (e.g., list format), but it remains efficient.

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

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

With no output schema, the description fully details the return structure: tracked[] with time-series, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers history limits and caveats (decay from daily closes, not intraday). The tool's complexity is well-addressed.

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

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

Schema coverage is 100% but the description adds value by stating defaults (14 for days, '1wk' for window), clamping (days 2-30), and explaining the purpose of window as 'snapshot family'. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It names the resource (polymarket_edges snapshots) and the specific verb ('answers how long edge existed and is it shrinking?'). It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge 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?

The description implies usage for evaluating edge longevity with the example comparing fresh vs. old edges. However, it does not explicitly state when to use this tool over alternatives or provide exclusions. The context is clear but lacks direct comparative 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, idempotentHint, openWorldHint, and non-destructive. The description goes beyond by detailing what happens in each mode (walks the ladder, returns specific fields) and explicitly warns about risks (partial basket fills convert arb into unhedged directional position). No contradictions with annotations; the description adds full 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?

The description is relatively long but well-structured: it front-loads the purpose, uses bold/caps for emphasis on key terms, and breaks modes into clear blocks. Every sentence adds information (purpose, parameters, returns, risks). Minor wordiness could be trimmed, but it's efficient for the complexity.

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

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

Despite no output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc. for basket) and explains the verdict field. It also covers risk context (thin books, forced directional risk). This provides a complete picture for an agent invoking the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining mode-dependent semantics (e.g., size_usd: 'max spend on buys, target proceeds on sells' for single-market, 'settlement notional S (shares per leg)' for basket) and default logic for 'side' in basket mode. This enriches the schema descriptions.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, telling the agent to 'USE THIS before acting' on their signals. This meets the bar for a specific verb+resource with sibling differentiation.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround may be uncapturable, partial fills create directional risk), effectively teaching the agent when not to skip this check. This is exemplary usage context.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. Description adds extensive behavioral context: two modes, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and explains when spreads are meaningful vs not. 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?

Dense and informative; front-loads purpose, then covers modes, response, and safety fields. Slightly long but each sentence adds value. Could benefit from bullet points or section headers but is effective as-is.

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 (3 parameters, no output schema), description is very complete. Covers modes, response structure (leg prices, top spreads, compatibility fields), temporal alignment, and when spreads are invalid. No gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. Description enhances meaning: explains topic values (lists 10 shortcuts) and that explicit parameters override mapped topics. Adds context beyond schema.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts and explicit event IDs) and describes response contents. Unique among siblings; no overlap with other 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?

Provides explicit guidance on when to use each mode and warns that most pre-mapped topics return compatibility_warning, indicating when spreads are not meaningful. Could be improved by explicitly mentioning alternative tools (e.g., polymarket_edges) for cases where compatibility is low, but already contains valuable usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it returns attribute rows and geometry, which is not in 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?

Three sentences: core purpose, parameter summary, usage tip. No wasted words. Front-loaded with key information.

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

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

No output schema, but mentions return type (attribute rows and geometry). Covers core behavior and parameters well. Lacks error handling details, but adequate for the tool's complexity.

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

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

Schema coverage is 100% with good descriptions, but the description adds context: SQL-like nature, defaults (limit 50), and examples for where and out_fields. 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?

Clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, referencing sibling tool search_datasets for obtaining the URL. This distinguishes it from siblings like layer_info.

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

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

Provides SQL-like parameter descriptions and examples like 'where="1=1" + out_fields="*" to sample'. Implicitly suggests use after search_datasets, but no explicit when-not-to-use.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. This goes beyond annotations.

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

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

The description is three sentences with no filler. It front-loads the main action and includes all essential information (usage, scope, related tools). Every sentence earns its place.

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

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

For a simple tool with one optional parameter, clear annotations, and no output schema, the description covers everything: purpose, usage, scope, and relationship to siblings. It is complete and self-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 coverage is 100% with one optional parameter 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this but adds no new parameter-level detail. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses specific verbs (retrieve/list) and identifies the resource (memory values/keys). It implicitly distinguishes from sibling tools like remember and forget by mentioning them.

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

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

The description explains when to use the tool: 'look up context the agent stored earlier... without re-deriving it from scratch'. It also notes it is 'scoped to your identifier' and instructs to 'omit the key argument' to list all keys. While it doesn't explicitly state when not to use it, the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: it returns specific fields, the mark_read flag affects subsequent calls by marking events read, and polling is acceptable. This adds value beyond annotations.

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

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

The description is concise and well-structured, starting with the core purpose, then detailing return values, filtering, mark_read behavior, and polling. Every sentence adds value without redundancy.

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

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

For a simple tool with no output schema, the description covers return fields, filtering options, the mark_read flag, polling suitability, and an alternative access method. No critical information is missing, making it fully actionable.

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

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

Schema coverage is 100% with parameter descriptions. The description enriches this by providing an example for type ('sec_8k'), clarifying since as ISO timestamp, and explaining the side effect of mark_read (so next call shows newer events). This adds 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?

The description clearly states the tool pulls fired events from the subscription feed, specifies the returned fields (source, citation_uri, raw event payload), and mentions filtering capabilities. It is distinct from sibling tools like subscribe or list_subscriptions, which manage subscriptions rather than retrieve alerts.

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

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

The description explains filtering by type and/or since, the mark_read option, and that polls work fine. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or contrast it with other tools, 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 disclose readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: fans out to multiple sources, GDELT→GNews fallback mechanism, USPTO soft-fail due to API sunset, and return structure (changes grouped by source, total_changes count, citation URIs). No contradictions with annotations, though rate limits or concurrency are not mentioned.

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 example queries and efficiently packs multi-source logic, fallback behavior, and parameter guidance into two paragraphs. Slightly long but each sentence adds value; no filler.

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

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

Given the tool's complexity (multiple sources, fallback, future API deprecation) and absence of an output schema, the description covers the key aspects: source details, fallback, failure mode, and return structure. It could benefit from mentioning pagination or response size limits, but overall it is complete enough for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100% (baseline 3). The description adds meaning beyond schema: explains acceptable formats for `since` (ISO date or relative shorthand) with examples, clarifies that `type` only supports 'company' currently, and provides typical usage hints for `since`.

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 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool 'entity_profile' by noting that sibling is for static profiles regardless of time window.

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 examples of query types ('What's new with X', 'latest on Y') and when to use the alternative ('Use entity_profile instead when you want the static profile'). Also provides guidance on the `since` parameter format and typical values like '30d' or '1m'.

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 set idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral details: key-value scoped by identifier, persistence duration, and pairing with recall/forget. 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 concise and front-loaded with the primary purpose, followed by usage guidance and technical details. Every sentence contributes value with no redundancy.

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

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

Given no output schema, the description implies successful storage through context. It mentions pairing with recall and forget, providing sufficient context for a simple storage tool. Slight gap: no explicit mention of return value or error handling.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description reiterates usage and offers examples but does not add significant meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses specific verbs (save, store) and distinguishes from sibling tools recall and forget by mentioning them explicitly.

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 advises use 'when you discover something worth carrying forward' and contrasts with recall/forget. It provides context on persistence (authenticated vs anonymous sessions) but does not explicitly state when not to use it.

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

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

Annotations already declare idempotent, read-only, open-world, non-destructive behavior. The description adds value by revealing internal cascading lookups ('replaces 2-3 manual lookups') and detailing the exact return fields per type. No contradiction with annotations.

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

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

The description is concise yet information-dense, using query examples and bullet-style formatting. Every sentence serves a purpose, no filler, and the key instruction is front-loaded.

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

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

Given the tool's modest complexity (2 required params, no output schema), the description fully covers what the tool does, how to use it, what it returns for each type, and even provides URI citation patterns. No gaps remain.

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

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

Schema already covers type and value with 100% description coverage. The description adds meaning: for company, it accepts ticker, CIK, or name with auto-disambiguation; for drug, brand or generic name. It also specifies the output fields, which the schema lacks (no output schema).

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

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

The description explicitly states it resolves a name to an official identifier, opens with clear query examples, and distinguishes between 'company' and 'drug' types. It leaves no ambiguity about the tool's core function.

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

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

Directly instructs 'Use FIRST whenever you have a name but need an ID', which is a strong usage guideline. It also lists supported types and what each returns, implicitly telling when not to use it (if you already have an ID).

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds details: probes each entity, ranks by score, returns score/confidence/signal density. Fully discloses behavior beyond annotations.

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

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

Three sentences, front-loaded with purpose and result. Every sentence adds value: function, use case, output format. No filler.

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

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

No output schema but description explains return: ranked list with score, confidence, signal density. Covers purpose, parameters, usage, and output. Complete for a tool with 4 params and rich annotations.

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 100% (baseline 3). Description provides additional context: entities array (2-8, first as subject), models (free default vs paid), context for disambiguation. Adds meaning beyond schema.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score. Specific verb+resource (scan_competitor_ai_presence) and distinguishes from single-entity sibling ai_visibility_check.

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 useful for competitive AI-marketing audits with example. Implicitly distinguishes from ai_visibility_check (single entity) but lacks explicit when-not-to-use or alternative naming.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds extra transparency: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list. No contradiction with annotations.

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

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

The description is well-structured, starting with a concise summary, then usage, return details, limitations, and edge cases. 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 no output schema, the description fully explains return values: summary block fields, per-advisory, links, alternative versions. Also covers partial failures and ecosystem limits.

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

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

Schema coverage is 100% with descriptions. The description adds that scoped packages are accepted and version defaults to latest, providing slight additional clarity beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools like deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also specifies NPM ecosystem only in v1 and directs to deps.dev:version for other ecosystems, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds useful context about return format and downstream usage, but does not reveal additional behavioral traits like rate limits or response size.

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

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

Two sentences, front-loaded with action and purpose, no wasted words. Efficient and clear.

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

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

Given the tool has 3 optional parameters, no output schema, and high schema coverage, the description is complete enough for an agent to understand and invoke it correctly. Minor gap: no mention of pagination or what happens with no results, but that is not critical.

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

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

Schema coverage is 100%, parameters are described well. Description adds value by explaining that the returned url is meant for query_layer / layer_info, which is extra semantic beyond the schema.

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

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

Description clearly states it searches City of Johnson City GIS open geospatial datasets by keyword, listing example datasets (parcels, zoning, public works) and specifies returned fields (name, summary, record_count, owner/org, Feature Service url). It also distinguishes from siblings by referencing query_layer and layer_info as downstream 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?

Describes how to use (search by keyword) and hints at next steps (pass url to query_layer or layer_info). However, it does not explicitly state when not to use this tool or compare with alternative search tools in the sibling list.

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

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

The description discloses the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars), and truncation/flagging behavior. All annotations are consistent and the description adds significant detail beyond them.

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 succinct with no redundant sentences. It front-loads the core purpose, then efficiently covers usage, pairing, and technical details. Every sentence is informative.

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

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

Given the tool has no output schema, the description adequately explains the return format (passages with character offsets and similarity scores). It also covers edge cases (truncation), pairing, and technical limits, making it fully self-contained for an agent.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by providing examples for the query parameter and clarifying the text size limit and default/max for limit. While the schema already covers basics, the description enriches understanding.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by focusing on internal search of an already-fetched record, and pairs with 'ask_pipeworx_grounded' for a different use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded' for grounding over passages. This provides clear context and an alternative approach.

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, such as SMS delivery caps (10/day), webhook auto-disable after 10 failures, and the one-time return of the signing secret. This complements the readOnlyHint and destructiveHint 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-front-loaded with the core purpose and is comprehensive, but at 10 sentences it could be slightly more concise by reducing repetition of delivery channel details also present in the schema.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: authentication requirements, supported types with examples, delivery channels, and operational constraints (caps, failure handling).

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

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

With 100% schema coverage, the description adds detailed examples and explanations for each parameter and subproperty, clarifying type-specific filters and delivery channel constraints beyond what the schema alone provides.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear usage context, including requirements (Pipeworx OAuth account) and type-specific details. However, it does not explicitly contrast with alternative tools (e.g., when to use list_subscriptions or unsubscribe), leaving some implicit guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: returns example questions with concrete tool calls, explains the structure of output. 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?

Description is thorough and well-structured with front-loaded triggers, then explanation. Slightly long but every sentence adds value. Could be trimmed slightly without losing information, but still excellent.

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 purpose (onboarding, discovery) and the richness of context from annotations and schema, the description is complete. It covers usage, parameter behavior, output nature, and integration with the broader tool ecosystem. No output schema needed due to clear output 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 has 100% coverage for the single parameter 'topic'. Description adds extra semantics: lists valid focus areas (finance, pharma, etc.) and explains behavior when omitted ('full spread'). This substantially improves 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 as the onboarding entry point, answering queries like 'what can I ask?' and distinguishing it from sibling tools by being the first tool to use when unsure. It specifies the output: category-bucketed example questions with exact tool+argument shapes.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with optional topic parameter. Provides clear when-to-use guidance and differentiates from other tools.

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

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

Annotations indicate mutation (readOnlyHint=false), no destruction (destructiveHint=false), and idempotency (idempotentHint=true). The description adds valuable context: the row is deactivated not deleted, and historical events remain available via recent_alerts. No contradictions.

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

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

Two sentences with zero waste. The purpose is front-loaded, and every sentence adds essential information (ownership, deactivation behavior, historical data availability).

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 the purpose, behavior, side effects, and constraint. It explains what happens to the row, which is sufficient for an agent to invoke 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 a single 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description repeats this but adds no additional semantic context beyond what the schema provides.

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

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

The description states the tool cancels a subscription by ID, with specific verb 'cancel' and resource 'subscription'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying ownership enforcement and deactivation behavior.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. While no alternatives are mentioned, the context is clear for a simple cancellation action.

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 behavioral details such as exact percent-delta math for financial claims and the fallback to a grounded pipeline. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads with common query patterns, then describes the two processing paths, and ends with the return format. No wasteful words, but it could be slightly more structured with bullet points for readability.

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

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

Despite no output schema, the description fully explains the return value: verdict (with enumerated options), actual value with citation, and reasoning. It covers both processing paths and their criteria, making it self-sufficient for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described well. The description adds minimal additional meaning (e.g., tolerance_pct override default, implied from wording), but the schema already covers the core 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 starts with explicit query examples like 'Is it true that…' and defines the tool as natural-language claim verification. It clearly distinguishes between company-financial claims (fast path with SEC EDGAR+XBRL) and other claims (grounded pipeline), setting it apart from sibling tools like ask_pipeworx_grounded or 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?

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two processing paths. However, it does not explicitly list when not to use the tool or mention alternative tools for subjective or unsupported claims.

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