Arcgis Tucson

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

Annotations indicate readOnly, openWorld, idempotent, and not destructive. The description adds that the default model is free, probing with Anthropic requires a BYO key and direct payment, and the output includes per-model details plus combined view. No contradictions.

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

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

The description is two sentences plus a third on usefulness. It is front-loaded with the main action and provides necessary details without fluff. Every sentence adds value.

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

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

Given the four parameters and no output schema, the description covers the purpose, parameters, and usage well. It could benefit from briefly mentioning the output structure (e.g., keys like score, confidence), but the core information is present.

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%, but the description adds extra context: default model, API key usage, and context disambiguation. For example, it clarifies that _apiKey is passed through to Anthropic, and context helps disambiguate common names.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the output (visibility score 0-100). It also names the default model and BYO key option. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which might be similar but this one explicitly scores 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 explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to provide _apiKey (if 'anthropic' is in models). It does not explicitly state when not to use, but the contexts given are sufficient.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable context: it routes to thousands of tools, returns structured data with stable citation URIs, and covers many domains. 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 verbose but well-structured: key directive first, followed by usage scenarios, examples, and alternatives. Every sentence adds value, though slightly longer than necessary.

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

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

Given the tool's complexity and absence of output schema, the description fully covers purpose, when to use, alternatives, examples, return format (structured answer with citations), and compatibility. No gaps.

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

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

Input schema has 6 parameters (all aliases for 'question') with descriptions. Schema coverage is 100%. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it routes factual questions to a wide range of authoritative sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when each should be used.

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 to prefer over web search for factual queries, provides specific examples, and clearly indicates when to step up to alternatives (hallucination-resistant single answer vs. broad multi-part queries). Also notes it works on every tier and is a fast single call.

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

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

Beyond annotations (readOnly, idempotent, openWorld), description adds key behaviors: cost of extra LLM call, process of routing among 4,552 tools, return structure with evidence and refusal reasons, and explicit refusal cases. There is no contradiction with annotations.

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

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

The description is a single informative paragraph that front-loads purpose and key differentiator. It is relatively concise given the amount of detail, but could benefit from bullet points for structure.

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 routing and extraction and the lack of output schema, the description covers return value structure and refusal reasons well. It omits edge cases or error details but is sufficient for agent understanding.

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

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

Schema coverage is 100% (all six parameters are documented as aliases for 'question'), so baseline is 3. The description adds no new meaning beyond explaining that the question is natural language; it does not elaborate on usage or constraints of the 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?

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, and distinguishes it from sibling ask_pipeworx by noting the extra cost and use case. The verb 'extracts' and resource 'answer from tool results' 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?

Explicitly states when to use (when answer will be quoted, cited, or acted on, with examples like financial verdicts) and when not to (casual lookups, preferring ask_pipeworx). This provides clear guidance on alternatives.

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

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

The description extensively discloses behaviors beyond annotations: resolver contract with market_match_confidence, parent_event extractor, news fields with fallback handling, safety short-circuiting, closed-market blocking, wide-spread indicators, and cancellation-rule risk. These details add significant value, with no contradictions to the readOnlyHint and idempotentHint annotations.

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

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

The description is verbose, containing extensive technical details (e.g., specific fan-out examples, resolver contract) that are valuable but could be condensed. The purpose and usage are front-loaded, but the length may hinder quick scanning.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers behavior, safety, edge cases, cancellation rules, and response structure, ensuring an agent has sufficient information to select and invoke the tool correctly.

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

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

With 100% schema coverage, the description adds meaning beyond the schema: examples for market input, clarification of depth enum defaults, and explanation of include_raw behavior. It provides context that helps the agent understand parameter usage.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, accepting a slug, URL, or question text. It explains the output (evidence packet + market-model comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edge_tracker or polymarket_arbitrage, which could cause confusion for an agent.

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 usage examples like 'should I bet on X' and mentions blocking conditions (low-confidence, closed markets, wide spreads). It implies when to use but does not state when not to use or mention alternative tools, 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 indicate read-only, idempotent, and non-destructive. The description adds depth: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), sorting by primary metric, handling off-calendar fiscal years, and returning citation URIs. 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?

Description is front-loaded with concrete example queries, then concisely explains capabilities. Every sentence adds value, covering entity types, data sources, sorting, and efficiency. No redundant or vague statements.

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 return format (paired data + citation URIs), data sources, metric details, and edge cases (off-calendar fiscal years). It is complete for a 2-parameter tool with 100% schema coverage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches by explaining that 'company' pulls revenue/net income/cash/debt from latest 10-K and 'drug' pulls adverse-event counts/approvals/trials. For values array, it specifies expected formats (tickers/CIKs for companies, names for drugs).

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in a single call, using example queries like 'compare X and Y' and 'which is bigger'. It distinguishes itself from sequential lookups by emphasizing parallel efficiency.

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

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

Explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use scenarios. Examples like 'rank these companies' and 'head to head' further guide selection.

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

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

Adds significant context beyond annotations: account requirement, paid tier, parallel decomposition into 4,552 tools, return format with gaps[], expected latency. All consistent with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

The description is dense but well-structured: front-loaded with requirements, then functionality, use cases, and caveats. Every sentence adds value, but slightly verbose for a simple tool.

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

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

For a complex tool with no output schema, the description comprehensively explains the return format (findings packet with evidence, confidence, source, etc.), limitations (empty gaps for non-structured topics), and expected timing, leaving no major gaps.

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

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

Schema coverage is 100% (baseline 3). Description adds concrete numbers for 'depth' (quick=3, standard=5, thorough=8) and clarifies that 'question' can be broad/multi-part, exceeding schema documentation.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and contrasts it with open-web search. It distinguishes from siblings by specifying when to use ask_pipeworx instead, making the purpose unambiguous.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not (single lookups, breaking news). Provides alternative tool names (ask_pipeworx) and prerequisites (account, paid plan for 'thorough').

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed.' 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 informative but slightly verbose. It is front-loaded with the key action and context, then lists domains and return details. Could be tightened but remains clear and scannable.

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

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

Given no output schema, the description adequately explains what is returned (top-N tools with schemas and examples). It covers purpose, usage, parameters, and outcome. No gaps identified for this discovery tool.

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

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

Schema coverage is 100%. The description adds examples and clarifies that 'query' accepts natural language and has many aliases (task, q, description, search). This adds meaning beyond the schema's property 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: 'Find tools by describing the data or task.' It specifies the action (discover, browse, search) and the resource (tools). It distinguishes from sibling tools by focusing on discovery rather than specific tasks.

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 (not just one answer).' Provides clear when-to-use context and implies when not to use (when you already know the tool). Includes example queries for 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 mark read-only and idempotent. The description adds context: parallel fan-out across multiple APIs, soft-fail for patents, and unsupported name inputs. Does not explicitly address invalid ticker/CIK behavior, but overall transparent.

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 with information but slightly long; front-loaded with purpose and examples. Could be slightly shortened, but structure is logical and each sentence adds value.

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

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

Given no output schema, the description fully explains return fields, data sources, failure modes (patent soft-fail), and limitations. Covers all essential aspects for an agent to use the tool correctly.

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

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

Adds significant meaning beyond schema: explains type enum limitation (only company), value format (ticker or zero-padded CIK), and explicitly warns against using names, directing to resolve_entity. Schema coverage is 100%, but description enriches 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 defines the tool as a holistic profile of US public companies, listing specific data sources and outputs (filings, fundamentals, patents, news, LEI). It distinguishes from sibling tools by explicitly stating preference over chaining single-pack lookups.

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

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

Provides explicit example queries, when to use (holistic view), when not to use (names only, requiring resolve_entity first), and notes patent soft-fail. Includes clear alternative 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 destructiveHint=true and idempotentHint=true; description adds 'delete' verbal confirmation but no additional behavioral detail beyond what annotations imply.

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 wasted words: action, use cases, and related tools all covered efficiently.

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

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

For a simple one-parameter destructive tool without output schema, the description is adequate, though no mention of permanence or bulk operations.

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 the key parameter completely (100% coverage), and the description adds no new meaning beyond 'by key'.

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 uses specific verb 'delete' and resource 'memory by key', clearly distinguishing it from sibling tools like remember and recall.

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

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

Explicitly states when to use (stale context, task completion, clear sensitive data) and mentions pairing with related tools, but lacks explicit when-not scenarios.

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 explains the process: fetches the page, extracts metadata, emits standard markdown. This adds value beyond the annotations (readOnlyHint, idempotentHint) by detailing the internal steps and output format. 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: two sentences plus a list of use cases. It is front-loaded with the core purpose and includes no redundant information. 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 two parameters and no output schema, the description covers the key aspects: what it does, how it works (fetch, extract, emit), output format (text blob), and use cases. It could mention error handling but is otherwise complete.

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

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

Schema coverage is 100% with both parameters described. The description does not add significant new meaning beyond the schema—it merely restates the url example and mentions default/max for max_links, which are already in the schema. 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 function: generating a production-ready llms.txt file for a URL. It specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on the specific output format and use cases.

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: getting a client's site indexed, drafting for own project, auditing competitor. It does not list when not to use it or alternative tools, but the context is clear enough for the agent to decide when to invoke this tool over similar ones.

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 true, and destructiveHint false, covering safety. The description adds no behavioral context beyond the annotations, such as authentication needs or rate limits. Since annotations carry the burden, a 3 is appropriate.

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

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

The description is a single, well-structured sentence that front-loads the action and resource. Every word 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 one parameter, full schema coverage, and safety annotations, the description provides a complete overview of the output: fields, geometry type, record count, and capabilities. No gaps are evident.

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

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

Schema coverage is 100% with a clear description of the 'url' parameter and an example. The tool description adds minimal extra meaning beyond the schema, so baseline 3 is justified.

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

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

The description clearly specifies the action 'Get' and the resource 'ArcGIS Feature/Map Service layer's schema', listing specific returned elements: fields, geometry type, record count, capabilities. It effectively distinguishes from sibling tools like 'query_layer' which handles data 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 includes 'by url' and provides an example, giving clear usage context. It does not explicitly contrast with alternatives, but the resource and intent are well-defined, making it easy to infer when to use this tool versus others.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need not restate. It adds value by specifying the response fields and that it returns only active subscriptions by default, which is helpful for understanding behavior.

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

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

Two sentences with no wasted words. First sentence states purpose and output, second gives usage context. Front-loaded with key information.

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

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

For a simple list tool with one optional parameter and rich annotations, the description covers purpose, output fields, and usage guidance. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with parameter description. The description does not add new information about the single parameter beyond what 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?

Clearly states the tool lists the caller's active subscriptions and enumerates returned fields. The verb 'list' and resource 'subscriptions' are specific, and the tool is distinguished from sibling tools like subscribe, unsubscribe, and subscribe-related tools.

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

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

Explicitly provides usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool and hints at related actions.

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

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

Discloses rate limit (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily. 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?

Single paragraph that efficiently covers purpose, usage, constraints, and quota without redundant information. Every sentence is meaningful.

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 feedback tool with no output schema, the description adequately covers submission behavior, lifecycle (digests), and roadmap impact, making it complete for the task.

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 explaining each enum value in context and clarifying that 'context' is optional, aiding correct parameter selection.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than 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?

Explicitly lists when to use each feedback type (bug, feature, data_gap, praise) and provides a key 'don't' (don't paste end-user prompts). Also mentions rate limits and quota effects.

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 value by disclosing the self-aggregating nature, data source (CF analytics-engine), no PII, and caching details (5min-1h). 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 (three sentences), front-loaded with purpose, then use cases, then technical details. Every sentence serves a purpose 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 1 optional parameter and no output schema, the description fully covers: return values (top tools, packs, volume), data source, privacy, caching, and parameter semantics. No gaps remain.

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

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

Schema coverage is 100% with description for the single parameter 'window', including enums and explanation of shorter vs longer windows. The description further adds context about what each window reveals, 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 returns top tools, top packs, and total call volume over a window. It uses specific verbs (returns, discovering, confirming, seeing) and distinguishes itself from sibling tools by focusing on trending/aggregated 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 three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case). It implies when to use (for trend insights) but does not explicitly state when not to use or name alternatives. However, the use cases are clear and actionable.

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 extensive behavioral traits beyond the annotations, including the algorithms used (monotonicity violations, partition-sum checks), semantic anchor for cross-event pairs, partition filter for placeholder slugs, and the fill check mechanism that advises against trading when realizable edge is ≤0. No contradiction with annotations (readOnlyHint=true, idempotentHint=true).

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

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

The description is front-loaded with the main purpose and modes, but it is quite lengthy (multiple paragraphs). While every sentence adds valuable detail, some trimming could improve clarity. The structure is logical, but the verbosity prevents a perfect score.

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 describes the response structure, including fields like gap_pp, suggested_trade, reasoning, and partition_check details. It also explains the fill check behavior and when not to trade. This is comprehensive for a complex analysis 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?

The input schema already has 100% coverage with descriptions for both parameters. The description adds significant meaning by providing concrete examples of slugs and topics, explaining how each mode uses the parameter, and detailing the behavior differences. This adds value beyond the schema, warranting a 4.

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

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

The description begins with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between two modes (event and topic) and explains the unique mechanisms. While it doesn't explicitly differentiate from sibling tools like polymarket_edges or polymarket_fill_risk, the depth of explanation makes the purpose unmistakable and distinct.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends 'event (recommended for a specific market)' and even mentions an alternative tool for custom sizing (polymarket_fill_risk). This is exemplary usage guidance.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent. Description adds deep behavioral details: model family logic, edge computation (including slippage and Kelly fractions), diagnostics for empty segments, 1h KV-level caching, and Fed bets disclaimer. No contradiction with annotations.

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

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

Front-loaded purpose, but overall very verbose. Detailed model family explanation could be shortened. While structured, the length may impede quick parsing by an AI agent.

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

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

Given 9 parameters and no output schema, description is remarkably complete. Covers response top-level structure, diagnostics, Fed markets treatment, and caching behavior. Addresses edge cases and provides rationale for design choices.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value beyond schema descriptions: explains use cases for slippage_pp, tradeable-edge filters, and min_partition_leg_kelly. Provides concrete defaults and examples.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. Explicitly built for 'what should I bet on today'. Distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing three specific opportunity segments.

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

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

Describes core use case: discover opportunities without paging hundreds of markets. Provides extensive guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and filters (min_kelly, min_edge_pp). Lacks explicit when-not-to-use compared to sibling tools, but overall usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds substantial behavioral details: uses daily snapshots, bounded by 60-day TTL, decay from daily closes not intraday, response structure, and explanation of snapshot gaps. This far exceeds what annotations provide.

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

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

Description is dense but well-structured, starting with purpose and then detailing response fields in a clear format. Every sentence adds value, though slightly verbose. Could be trimmed slightly but remains readable.

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

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

Given simple parameters and rich annotations, the description fully covers the tool's behavior: response fields, edge cases (gaps, TTL, expired opportunities), and assumptions. No output schema exists, but response details are thoroughly explained.

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 (100%). Description adds meaning: default values (14 days, 1wk), clamping (2-30), and context about snapshot family. While schema has clamp info, description clarifies behavior and adds practical defaults.

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: analyzing edge persistence and decay from polymarket_edges snapshots. It differentiates from sibling tool polymarket_edges by providing higher-level telemetry. The verb 'Answers' and specific question make the purpose unmistakable.

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

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

The description explicitly answers 'how long has this edge existed and is it shrinking?' which guides when to use. It does not explicitly say when not to use or name alternatives, but the sibling list suggests polymarket_edges for raw data. Still, clear context is provided.

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 behavioral context about order book walking, slippage, fillability verdicts, and forced directional risk. 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?

Well-structured with line breaks separating modes, front-loads purpose. Though verbose, every sentence adds value; minor wordiness prevents a 5.

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 comprehensively details return fields for both modes, covers defaults, and addresses edge cases like partial basket fills and directional risk, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, but the description adds meaning beyond schema: clarifies default behavior for 'side' in basket mode (auto from partition sum) and explains 'size_usd' interpretation for single vs basket modes.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and distinguishes between single-market and basket modes with specific return fields. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides clear when-to-use scenarios and warns about risks of partial fills and uncapturable theoretical overround.

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

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

Adds significant context beyond annotations: two modes, compatibility fields, temporal alignment, skipped cross types. Annotations already mark readOnly, idempotent, non-destructive; description reinforces and expands without contradiction.

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

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

Well-structured with clear sections but somewhat verbose; some redundancy (e.g., 'the two venues sometimes price...') and final caution could be trimmed.

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, description thoroughly explains response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases, making it complete 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 parameter descriptions; description adds mode explanation, concrete examples, and override behavior, enhancing understanding beyond schema alone.

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

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

Clearly states it computes cross-venue spread for the same resolving question, distinguishing two modes (topic shortcuts and explicit tickers) and differentiating from sibling tools like polymarket_arbitrage.

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

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

Explains when to use (comparing prices across venues) and when not (when compatibility_warning fires). Provides caution about real spreads being rarer than shortcuts suggest, but lacks explicit mention of alternative tools.

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

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

Annotations already indicate read-only, idempotent. Description adds return type (attribute rows and geometry) and URL format, enhancing transparency.

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

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

Three sentences: purpose, return, usage tip. No fluff, front-loaded with key info.

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

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

Covers purpose, parameters, and return. No output schema, but mentions attributes and geometry. Could mention pagination behavior, but sufficient for a query tool.

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

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

Schema coverage is 100%, but description adds examples (SQL-like where, comma-separated out_fields, defaults) and a concrete usage pattern, significantly adding meaning.

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

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

Clearly states verb (Query), resource (ArcGIS Feature/Map Service layer), and how to get URL (from search_datasets). Distinguishes from siblings like search_datasets and 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 a usage tip (where='1=1'+out_fields='*' to sample) and implies relationship with search_datasets, but no explicit when-not-to-use or 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=true and destructiveHint=false, so the description adds value by stating scoping by identifier and pairing with remember/forget. 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?

Three sentences are efficiently structured: first states core action, second provides use cases, third adds scoping and pairing. Front-loaded and no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and pairing with siblings. Annotations cover safety. No gaps.

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

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

Schema coverage is 100% with a meaningful description for the key parameter. The description adds context that omitting the key lists all saved keys, reinforcing and expanding 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 retrieves a saved value or lists all keys, with specific verb-resource pairing ('retrieve a value', 'list all saved keys') and distinguishes from siblings (remember, forget) by naming the action and pairing.

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

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

The description explains when to use (look up stored context) and how to list all keys (omit key argument), with concrete examples. It does not explicitly state when not to use, but the use case is clear and paired with remember/forget.

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 important behavioral detail: setting mark_read:true flags events as read, affecting subsequent calls. Also mentions the same feed is available via a GET endpoint. Annotations already declare readOnly and idempotent, so description adds value beyond annotations without contradiction.

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

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

Single paragraph with effective front-loading of purpose. Could be slightly more structured, but every sentence adds value and no redundancy.

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

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

Despite no output schema, the description enumerates return fields (source, citation_uri, raw event payload). Covers filtering, polling, and alternative access. Complete for a read-only, idempotent tool.

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

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

Schema coverage is 100%, but the description adds concrete examples ('sec_8k'), clarifies the purpose of mark_read, and explains the limit default. Greatly enhances understanding beyond the schema alone.

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

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

Clearly states 'Pull fired events from your subscription feed' and lists what it returns (source, citation_uri, raw event payload). Distinguishes from sibling tools like list_subscriptions, which deals with subscriptions rather than events.

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

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

Provides clear context for filtering by type and since, and mentions polling is fine. Lacks explicit when-not-to-use or alternative recommendations, but the usage is well-defined.

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 (readOnlyHint, etc.), the description details the internal behavior: fan-out to SEC, GDELT/GNews with fallback, USPTO soft-fail, and return structure (changes[], total_changes, citation URIs). It fully discloses the tool's behavior.

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

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

The description is concise and front-loaded with examples. It covers all necessary aspects without excessive verbosity. However, it could be slightly more streamlined by removing some examples, 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?

Given there is no output schema, the description adequately describes the return format (changes grouped by source, total_changes count, citation URIs). It also covers the data sources, fallback behavior, and the window parameter. It is complete for an agent to understand usage and output.

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 providing usage examples for `since` (e.g., '7d', '30d', '3m', '1y'), explaining `value` can be ticker or CIK, and giving typical values. This goes beyond the schema definitions.

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

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

The description clearly states the tool returns a change feed for a company over a recent window, with specific examples ('What's new with X'). It distinguishes itself from the sibling entity_profile, which is for static profiles. The purpose is unambiguous and 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?

The description explicitly tells when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile...'). It also provides example queries and clarifies the window parameter. This gives clear guidance on usage and alternatives.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: memory scoped by identifier, persistence for authenticated users versus 24-hour retention for anonymous sessions. 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 (4 sentences) and well-structured: starts with core purpose, then usage guideline, then technical details. Every sentence adds 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?

For a simple two-parameter tool with no output schema, the description covers purpose, usage, parameter semantics, behavioral traits, and pairing with sibling tools. It is complete and self-contained.

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 both key and value have descriptions in the schema. The description adds examples for key and value but does not provide significant new meaning beyond the schema, meriting a baseline 3.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with verb 'save' and resource 'data'. It distinguishes from sibling tools 'recall' and 'forget' by explicitly naming them as paired 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 when-to-use context: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Mentions alternative tools 'recall' and 'forget' but does not explicitly state when not to use, though it is implied.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that each call cascades through several lookup endpoints, providing insight into internal 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?

The description is somewhat long but every sentence adds value. It uses examples and enumeration of return types efficiently. Could be slightly more terse but maintains clarity.

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

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

Despite no output schema, the description explains return values for both entity types in detail, including citation URIs and internal cascading. Covers all necessary context for a resolution tool with two parameters.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds concrete examples for 'value' (AAPL, 0000320193, ozempic) and details return types for each enum option, adding practical guidance.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes itself from siblings by emphasizing it's the first step when needing an ID, and it replaces multiple manual lookups.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides supported types and return values. Does not explicitly mention when not to use, but the context implies it's the primary resolution tool among siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds that it probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density, and treats first entity as subject. No contradictions; adds behavioral context beyond annotations.

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

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

Two sentences, front-loaded with main action, concise with no wasted words. Structure is clear and efficient.

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

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

No output schema, but description explains return values (ranked list with score, confidence, signal density per entity). Parameter count 4 with full schema coverage. Behavior of composite tool is well-explained. Lacks details on pagination or error handling, but acceptable for this complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains probes use ai_visibility_check, first entity treated as subject for narrative, and context parameter disambiguates common names. Adds value beyond schema.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side', specifies it probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (different comparison). Verb+resource+scope 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?

Explicitly says 'Useful for competitive AI-marketing audits' and gives example question. Implicitly contrasts with ai_visibility_check (single entity) and compare_entities. Lacks explicit when-not-to-use or alternatives, but context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds rich behavioral context: the composite nature, fanning out across two services, partial failures, bundlephobia's first measurement taking 5-30s, and listing sources_failed. This fully informs the agent of runtime behavior.

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

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

The description is lengthy but highly informative, front-loading the composite nature and core use case. Every sentence contributes meaningful details (ecosystem scope, partial failure behavior, return fields). Could be slightly tighter, but 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?

No output schema exists, yet the description enumerates all return components: summary block fields (is_latest, license, etc.), per-advisory detail, links, and a list of recent alternatives. It also covers edge cases like partial failures and ecosystem limitations, making it fully complete.

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

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

Schema covers both parameters at 100%. Description adds value by noting that scoped packages like '@types/node' are accepted for the 'package' parameter, and that 'version' defaults to the latest when omitted. This goes beyond the schema definitions.

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

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

The description clearly states the tool is a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the use case ('is X safe / popular / small' or 'what does adding lodash cost me') and distinguishes itself from sibling tools which are unrelated.

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 ('whenever an agent asks...') and what it returns. Also states limitations: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' Mentions partial failures and graceful degradation, guiding proper invocation.

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, covering safety and idempotency. The description adds context about the return fields (name, summary, record_count, owner/org, url), but does not add significant behavioral traits beyond what annotations provide.

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

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

The description is exceptionally concise: two sentences that front-load the purpose and follow with output and next steps. 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?

The description covers the return structure and next steps, but does not mention pagination or the effect of the limit parameter (which is optional anyway). Given the tool's moderate complexity and no output schema, it is mostly complete but could be slightly more thorough.

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 tool description does not add new information about parameters beyond what is in the schema, so it meets the baseline but provides no extra value.

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

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

The description clearly states the tool searches City of Tucson GIS datasets by keyword, specifies example dataset types, and describes the return fields. It distinguishes itself from siblings by mentioning that the returned URL can be used with query_layer and layer_info.

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

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

The description provides usage guidance by noting the returned url can be passed to query_layer/layer_info, implying this tool is for discovery. However, it lacks explicit 'when not to use' statements or comparisons to other sibling tools like search_within.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds technical details: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, with a 200K character cap and truncation flagging. Also mentions every passage includes character offsets for verification, going beyond annotations.

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

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

Two well-structured paragraphs. First sentence immediately states purpose. Each subsequent sentence adds value: usage context, pairing advice, technical details, and constraints. No superfluous 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 explains what is returned (top-N passages, character offsets, similarity scores) and how it works internally. Covers technical constraints (200K char cap, truncation), making it sufficient for agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds examples for the query parameter and notes the default and max for limit, but does not significantly extend beyond the schema's existing descriptions.

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

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

Clearly states it performs semantic search inside a fetched record, specifying the action and resource. Mentions it returns top-N passages with character offsets and similarity scores. While it pairs with ask_pipeworx_grounded, it does not explicitly differentiate from other sibling search tools like search_datasets.

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

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

Explicitly says to use when the record is too large for the prompt. Provides a concrete alternative: pair with ask_pipeworx_grounded for grounded responses. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description reveals important behaviors: feed always on, optional email/sms with a 10/day cap, and webhook auto-disabling after 10 consecutive failures. However, the idempotentHint annotation (true) is not addressed; the description implies creation of a new subscription each time without clarifying idempotency behavior.

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

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

The description is well-structured with front-loaded purpose and return value, followed by requirements, types, and delivery channels. It is informative but slightly lengthy, though each sentence adds necessary detail.

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

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

Given the complexity of 3 parameters with nested objects and no output schema, the description adequately covers prerequisites, type-specific parameters, and delivery constraints. However, it lacks clarification on idempotency and duplicate subscription 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?

With 100% schema coverage, the description adds substantial value by providing concrete examples for each type, including default values and optional fields. It also explains delivery channels in detail with validation constraints, far exceeding 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 explicitly states it 'Create a proactive monitoring subscription' and specifies it returns a new subscription ID. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts, which serve different purposes.

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

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

The description clearly states the prerequisite of a Pipeworx OAuth account and explicitly excludes anonymous/BYO users. It also lists supported types and delivery channels. However, it does not explicitly contrast with alternative tools or scenarios.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety. It adds useful behavioral context: the tool returns example questions with tool calls from a live catalog and describes its role as a discovery entry point.

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

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

The description is fairly concise and front-loaded with the purpose, but includes a long list of user queries (e.g., 'what can I ask?' that could be trimmed slightly. Still very effective.

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

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

For a simple tool with one optional parameter and no output schema, the description is comprehensive: it explains what it returns, how to call it, and when to use it, fully covering the tool's utility.

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 goes above and beyond by explaining that omitting the topic gives a full cross-category spread and listing example topics, adding significant value beyond the schema definition.

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

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

The description clearly states that the tool returns category-bucketed example questions to help users understand what Pipeworx can do, explicitly distinguishing it as an onboarding entry point from sibling tools like ask_pipeworx and entity_profile.

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

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

The description explicitly instructs to use this tool FIRST when the user does not know what Pipeworx can do, and explains how to call it with no arguments for full spread or with a topic to focus, providing 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?

Adds beyond annotations: explains deactivation vs deletion and relationship to recent_alerts. 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?

Two sentences, front-loaded with main action, no wasted words.

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

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

For a simple tool with 1 param, no output schema, the description covers effect, ownership, and side effects completely.

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

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

Single param well-described by schema and context ('by id'). Schema coverage 100%, description reinforces origin of id.

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

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

Clear verb 'Cancel' and resource 'subscription by id'. Distinct from sibling tools like subscribe and list_subscriptions.

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

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

States ownership constraint ('only cancel your own subscriptions') and mentions non-destructive behavior. Could explicitly note when not to use, but context is strong.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds extensive behavioral context: the use of SEC EDGAR + XBRL as authoritative sources, the specific output fields (verdict, structured form, actual value with citation, percent delta), and performance benefits. 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, with front-loaded example queries and clear structure. Every sentence adds value, covering purpose, scope, usage, output, and benefits. No unnecessary words.

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

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

Despite having no output schema, the description fully explains the output structure. It covers the tool's scope, limitations (company-financial claims), and integrates well with the annotations. The agent has enough context to select and use the tool correctly.

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

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

Only one parameter 'claim' with a good schema description (100% coverage). The tool description provides additional examples and context about the type of claims supported, but does not significantly enhance the parameter semantics 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: natural-language claim verification, with specific verb 'validate' and resource 'claim'. It provides multiple example queries and details the domain (company-financial claims). It distinguishes itself from siblings by highlighting that it replaces multiple sequential calls, though it doesn't explicitly name alternatives.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This provides clear context for usage. However, it does not specify when not to use it or mention alternative tools for non-financial claims, which would strengthen the guidance.

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