Arcgis Berkscounty

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

The description complements the annotations (readOnlyHint, idempotentHint, etc.) by detailing that the tool probes LLMs and returns per-model scores. It also discloses that Anthropic calls require a BYO key and incur direct charges, adding important behavioral context beyond the annotations.

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

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

The description is a single paragraph of four sentences, front-loaded with the primary purpose. Every sentence adds necessary information without redundancy. It is concise and well-structured.

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

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

Despite lacking an output schema, the description explicitly states the return format (per-model {score, confidence, signals, raw_response} plus a combined view). It covers all parameters and provides sufficient context for an AI agent to 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 description coverage, the baseline is 3. The description adds value by explaining the default model for 'models', the passing of '_apiKey' directly to Anthropic, and the disambiguation purpose of 'context'. This goes beyond what the schema provides.

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

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

The description clearly states the action (probe one or more LLMs), the resource (a business/brand/product/topic), and the output (score 0-100 per model). It distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description explains when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides context on default model and API key requirement for Anthropic. It does not explicitly state when not to use it or differentiate from similar sibling tools like 'scan_competitor_ai_presence', but the 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?

Annotations already indicate safe read-only behavior. The description adds value by explaining routing logic, citation URIs, and that it works on all tiers, but could further detail response format for edge cases.

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

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

Front-loaded with key instruction and well-structured, but slightly verbose with redundant listing of sources and examples. Still earns its length given tool complexity.

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

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

Given no output schema, the description explains the structured answer with citations. It covers usage, limitations, and integration with siblings, making it fully actionable for an agent.

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

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

Schema has 100% coverage and already describes aliases. The description adds examples but no additional semantic detail beyond the schema, fitting the baseline for high coverage.

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

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

The description clearly states it routes questions to a vast set of verified sources (SEC, FDA, etc.) and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making it 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?

It explicitly recommends preference over web search, provides clear when-to-use and when-to-step-up guidance, and includes numerous examples, covering both 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds crucial behavioral context: refusal reasons (not_in_source, no_tool_match, etc.), return fields (answer, evidence, confidence, source, fetched_at), and the extra LLM call cost. 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 yet packed with information. Key details are front-loaded ('Hallucination-resistant answer mode'), followed by clear explanation of behavior, return format, and use cases. Every sentence contributes value without redundancy.

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

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

Given the tool's complexity (6 parameters, no output schema), the description is complete. It explains the entire workflow: routing, fetching, extraction, refusal handling, and return structure. It also provides cost considerations and when to use vs. sibling.

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

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

Schema coverage is 100%, with all six parameters (including aliases) described. The description adds no additional meaning beyond the schema, but the schema itself is sufficient. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It specifically contrasts with the sibling ask_pipeworx by noting it extracts answers using only tool results, providing verbatim evidence. This distinguishes it effectively from 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?

Explicit guidance on when to use: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off of one extra LLM call, helping agents choose appropriately.

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 detailed behavior including market resolution, classification, fan-out, response shapes, safety short-circuits, closed market handling, resolution-rule risk, and more, far beyond the annotations which only indicate read-only and idempotent.

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?

While well-structured with clear sections (classifiers, fan-out examples, response shapes, safety), the description is verbose and contains excessive detail that could be overwhelming for an agent. It earns its place but lacks conciseness.

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

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

Extremely thorough: covers all edge cases (closed markets, low confidence, wide spreads, cancellation rules, news fallback), explains response shape in detail (result.market, result.analysis, result.evidence), and provides resolver contract. No output schema, so the description compensates fully.

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

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

Schema coverage is 100% with descriptions. The tool description adds significant value with examples, default behaviors (quick/thorough, include_raw), and explanations of how parameters affect fan-out and response size.

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 Polymarket bets by fetching Pipeworx data. It specifies inputs and use cases, but doesn't explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, leaving some ambiguity.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive context on behavior, safety, and resolution logic, effectively guiding an agent.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses that the tool makes external network calls (SEC EDGAR, FAERS), handles off-calendar fiscal years correctly, returns sorted results by primary metric, and provides citation URIs. It does not contradict annotations and adds valuable behavioral context.

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

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

The description is dense with useful information but slightly verbose with multiple natural language examples. It is front-loaded with key trigger phrases and use case. Every sentence adds value, though some repetition of the comparison concept could be trimmed. Overall efficient for the amount of context provided.

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

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

Given the tool's complexity (two entity types, external data sources, sorting) and lack of output schema, the description covers: data returned, metrics per type, sorting behavior, and citation URIs. It lacks explicit details on error handling or response format, but for a comparison tool the provided information is substantially complete.

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

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

Schema coverage is 100%, but the description adds significant meaning: for the 'type' parameter, it explains the data sources for each enum value. For the 'values' parameter, it clarifies expected formats (tickers/CIKs for company, names for drug) and constraints (2–5 items). It also explains sorting by primary metric, which is not in the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, specifies the exact data pulled for each type (SEC financials for companies, FAERS/trial counts for drugs), and distinguishes it from single-entity lookups. It uses specific verbs like 'compare' and gives concrete examples of trigger phrases, leaving no ambiguity about purpose.

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

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

The description explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities. It provides example natural language triggers and specifies the exact conditions for use (2–5 entities, company or drug). This gives clear when-to-use guidance and implies when not to use it (single entity).

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 key behaviors beyond annotations: requires account, paid plan for thorough depth, 15-60s latency, never invents answers (gaps[] for unknowns). Annotations already indicate read-only and idempotent, and description aligns without contradiction. Transparent about limitations for current events.

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 critical callouts (account required, alternative tool) and well-structured into sections. It is fairly long but every sentence adds value; minor redundancy (mentions 'not open-web search' multiple times) but overall efficient for the complexity.

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

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

Given the tool's complexity (2 parameters, no output schema, many siblings), the description covers all necessary aspects: prerequisites, alternatives, use cases, limitations, timing, output structure, and parameter behavior. An agent can make an informed choice without needing additional context.

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

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

Schema covers both parameters with descriptions; the description enriches them by explaining the depth values (quick=3, standard=5, thorough=8) and that question should be natural language, broad. This adds practical context 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?

The description clearly defines 'deep_research' as a multi-source research tool over structured data, explicitly contrasting with open-web search and sibling tools. It states the exact scope (1160 sources), the process (decomposes into facets, parallel routing), and the output format (findings packet with evidence and gaps).

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

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

Provides explicit guidance on when to use: broad/multi-part questions over structured data. Clearly states when not to use: single lookup (use ask_pipeworx), breaking/current news (use ask_pipeworx). Also explains account requirement and that free tier uses quick/standard, paid for thorough. This helps the agent decide correctly.

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 transparency: it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and notes results are 'ready to call directly, no second schema lookup needed.' 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 informative but slightly verbose. It is front-loaded with the core purpose and usage. Could be trimmed slightly, but 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 the tool's complexity (6 parameters, no output schema), the description is complete: it explains purpose, usage, output format (top-N tools with schemas), and even addresses potential follow-up by stating results are ready to call. 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 description coverage is 100%, so baseline is 3. The description mentions 'query' and 'limit' but does not add significant meaning beyond what the input schema already provides. Examples in the description mirror those in the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by positioning as a first-step discovery tool.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' While it lacks explicit when-not-to-use guidance, the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, mentions soft-fail for patents, and states it does a single parallel call. No contradiction with annotations.

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

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

The description is a single paragraph that is front-loaded with example queries, then explains the tool's behavior and return values. It is informative but slightly long; however, every sentence adds value. Minor improvement could be breaking into sections, but still 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 exists, but the description thoroughly explains the return shape: cik, company_name, recent_filings (with URIs), fundamentals, patents, news, LEI. It also notes data source details and the patents sunset. This provides sufficient context for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with two parameters. The description adds meaning: 'value' can be ticker or zero-padded CIK, and clarifies that names are not supported (referencing resolve_entity). For 'type', it notes only 'company' is supported. This goes beyond the schema's enumerations and 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: 'full cross-source profile of a US public company' with specific example queries like 'Tell me about X' or 'research Acme'. It distinguishes from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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

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

The description provides explicit when-to-use guidance (holistic view, one parallel call) and when-not-to-use (names not supported, with alternative: 'use resolve_entity first if you only have a name'). It also notes the patents API sunset May 2025, setting expectations.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds no further behavioral context beyond 'Delete', which is already implied by the name and annotations.

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

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

Three sentences, front-loaded with the action verb 'Delete'. 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?

With a single required parameter and no output schema, the description adequately covers purpose and usage. It does not detail behavior on missing keys or confirmation, but this is a simple destructive operation.

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

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

Schema coverage is 100% and the description's explanation of the key parameter ('Memory key to delete') adds no additional meaning beyond the schema's 'Memory key to delete'.

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

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

The description clearly states the verb 'Delete', the resource 'memory', and the method 'by key'. It also distinguishes the tool from siblings 'remember' and 'recall' by pairing them.

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

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

The description provides explicit use cases: 'stale context', 'task done', 'clear sensitive data'. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. Description adds that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' – confirming an external network request and output format, which 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?

Four sentences in a single paragraph, front-loaded with purpose. Every sentence adds value: purpose, process, output format, and use cases. 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?

Description covers purpose, process, output format, and use cases. For a simple tool with 2 params and no output schema, this is largely sufficient. Lacks mention of error handling or prerequisites (e.g., URL accessibility), but overall complete for decision-making.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds 'any URL' context and default/max for max_links, but does not significantly enhance understanding beyond the schema. Baseline of 3 is appropriate.

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

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

Description clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource, and distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility analysis.

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

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

Description lists concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' Lacks explicit when-not-to-use or alternatives, but context is clear from sibling tool names.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world, so the description does not need to repeat these traits. However, it adds specific behavioral details about the returned information (fields, geometry type, etc.). It lacks context on error handling if the URL is invalid or the layer is inaccessible, which would be useful.

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, then lists specific outputs. Every word adds value, with no redundancy or filler.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately covers the return values (fields, geometry type, record count, capabilities). It could briefly mention that the URL must be valid and point to an existing layer, but the current level is sufficient for most cases.

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

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

The schema provides 100% coverage with a clear description for the single 'url' parameter. The description mentions 'by url' but does not add extra semantics beyond what the schema already states. Given full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves schema information from an ArcGIS Feature/Map Service layer, specifying the exact data returned (fields, geometry type, record count, capabilities). This distinctively separates it from sibling tools like 'query_layer' which would query actual data rather than schema.

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 no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusion criteria. For example, it does not clarify that this tool should be used for metadata discovery rather than data retrieval, which would help an agent choose between 'layer_info' and 'query_layer'.

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

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

Annotations already set readOnlyHint=true, destructiveHint=false. Description adds context about returned fields and use cases, aligning with annotations. No contradictions.

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

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

Two sentences plus a usage hint, no redundancy, front-loaded with essential information.

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

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

Given no output schema, description lists return fields (id, type, etc.) and provides usage context. Adequate for a simple list tool, though pagination or ordering is missing.

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

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

Schema coverage is 100% with the include_inactive parameter described. The description adds minimal extra meaning beyond the schema, staying at baseline.

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

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

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing.

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

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

Description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide when to use this tool, though it doesn't explicitly state when not to use it.

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

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

Annotations are all false (non-destructive, etc.), but the description adds valuable context: free usage, rate limit, no tool-call quota impact. No contradiction with annotations. The description fully discloses behavioral traits 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 very concise: three sentences covering purpose, when to use, what to include, and constraints. No redundant phrases. Front-loaded with the core action.

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

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

For a single-direction feedback tool, the description covers all relevant aspects: input types, usage guidelines, rate limits, and quota info. No output schema exists, but that is acceptable since feedback likely returns no structured response. The context object is described in schema and referenced in guidance.

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

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

Schema coverage is 100%, so the description provides minimal parameter elaboration. The enum 'type' is already well-described in the schema. The description does not add new semantic meaning beyond what the schema already provides, making a score of 3 appropriate.

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

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

Description clearly states the tool collects feedback about broken, missing, or needed functionality. It specifies the team (Pipeworx) and the types of feedback (bug, feature, data_gap, praise). This distinguishes it from siblings like 'ask_pipeworx' or 'discover_tools' which are informational 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 states when to use: for wrong/stale data (bug), missing tools (feature/data_gap), or praise. Also advises not to paste end-user prompts but to describe in terms of tools/packs. Includes rate limit (5 per identifier per day) and notes it doesn't count against quota.

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

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

Description adds significant context beyond annotations: it explains the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h depending on window), and that it is self-aggregating. Annotations already indicate read-only, idempotent, and non-destructive, so no contradiction.

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

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

The description is informative but slightly verbose; it could be tightened without losing clarity. However, it front-loads the main purpose and uses bulleted use cases, making it easy to scan.

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

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

For a tool with one optional parameter and no output schema, the description provides all necessary context: return contents, caching, privacy, and use cases. The response format is implied and sufficient for an agent to decide usage.

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

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

With 100% schema description coverage, the schema already documents the 'window' parameter's enum values. The description adds useful context by explaining the behavior of different windows (short for hot now, long for steady-state), which helps the agent choose appropriately.

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 that the tool returns trending tools, packs, and call volume over recent windows. It uses specific verbs ('returns top tools, top packs, and total call volume') and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on aggregated trend 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?

Description lists three explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case with current demand. While it doesn't explicitly state when not to use or name alternatives, 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context: it explains the algorithm (monotonicity violations, partition checks, Jaccard similarity, placeholder filtering, fill checks with depth data), the conditions under which signals are valid (realizable_edge_pp > 0), and the response structure. 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 detailed but front-loaded with the core purpose and mode selection. It uses bullet points and clear labeling (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize information. A minor trim could reduce verbosity, but every sentence contributes necessary behavioral detail for correct tool usage.

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

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

Given the tool's complexity (multiple modes, algorithmic steps, fill checks) and the absence of an output schema, the description comprehensively explains all aspects: what it does, how to use each mode, the response structure, and even conditions to avoid trades. It is complete for effective agent invocation without requiring external docs.

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

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

Input schema has 100% coverage for both parameters (event, topic). The description adds meaning beyond the schema by explaining the format of event slugs, the role of a seed question for topic mode, and the behavior differences between modes. While the schema already describes the parameters, the description provides valuable operational context.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) with specific examples, and the verb 'Find' combined with resource 'arbitrage opportunities on Polymarket' is specific and distinct from sibling tools like polymarket_edges.

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

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

The description explicitly says when to use each mode: 'event' for a specific market with a slug, 'topic' for cross-event scanning with a seed question. It also references an alternative tool (polymarket_fill_risk) for custom sizing, providing clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false, indicating a safe, non-destructive tool. The description adds substantial behavioral details: model families, response segmentation, caching (1h at KV level), diagnostics, and tradeable-edge knobs. This goes far beyond the annotations, providing deep transparency into how the tool works and its data sources.

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 thorough but verbose (roughly 400 words). It uses structured paragraphs and all-caps for segment names, aiding readability, but contains some redundancy (e.g., knob explanations partially repeat parameter descriptions). Front-loading the purpose is good, but the density of technical details could be better organized for quick consumption.

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 the complexity (9 parameters, no output schema, multiple models), the description is remarkably complete. It explains model families, response structure (by_segment, fed_candidates, diagnostics), parameters as knobs, caching, and edge cases (e.g., Fed bets excluded, diagnostics for empty segments). An agent can understand how to invoke and interpret results without additional documentation.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds operational context beyond the schema, e.g., explaining how min_liquidity/max_spread_pp serve as 'Tradeable-edge filters' and how min_partition_leg_kelly applies specifically to partition leg Kelly. This enriches the schema's static definitions with dynamic usage 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 opens with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately establishes the tool's purpose as identifying betting opportunities, distinguishing it from siblings by focusing on Pipeworx disagreement and multiple model families. The phrase 'Built for "what should I bet on today"' reinforces the specific use case.

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

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

The description implies usage (e.g., 'agents discover opportunities without paging hundreds of markets') but does not explicitly state when to use this tool vs. siblings like polymarket_arbitrage or polymarket_edge_tracker. No when-not-to or alternatives are provided, leaving the agent to infer based on tool names alone.

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

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

Annotations indicate readOnly, openWorld, and idempotent. The description adds context: it computes trends from snapshots, explains data gaps due to cache-miss, and details expired opportunities. 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 detailed but well-structured, front-loading the purpose and then explaining args and response format. It could be slightly more concise, but every sentence adds value.

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

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

Despite no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) with fields and limitations. This is comprehensive for a complex 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 default values (14 days, '1wk'), clamp range for days (2-30), and clarifies 'window' as snapshot family. This adds meaning beyond the schema descriptions.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?'. It explicitly distinguishes its focus on time-series and decay from sibling tools like 'polymarket_edges'.

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

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

The description explains when to use it: to differentiate fresh edges from old ones, and contrasts with a generic edge query. It mentions limits like 60-day TTL and snapshot start, but does not explicitly state when not to use it.

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

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

Beyond annotations (readOnlyHint etc.), description details exactly what the tool does: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdicts (clean|degraded|cannot_fill). For baskets, explains theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], forced_directional_risk. No contradiction with annotations.

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

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

Well-structured with bold headings for modes and bullet points for outputs. However, it's relatively long (multiple paragraphs). Every sentence is informative, but some compression might have been possible without losing clarity.

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

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

Given the complexity of two modes and multiple outputs, the description is complete. It explains every output field, provides warnings about risks (forced_directional_risk, thin_legs), and covers edge cases. No output schema, but description compensates fully.

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

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

Schema coverage is 100%, but description adds meaning: clarifies size_usd interpretation per mode (max spend on buys, target proceeds on sells for single; settlement notional for basket). Explains side defaults and auto mode. Could have been more explicit about format (slug vs URL) but it says 'slug/URL'.

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'. It distinguishes itself from siblings like polymarket_arbitrage (which identifies arbitrage opportunities) by being a pre-trade risk assessment tool.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable on thin books, partial basket fills convert arb into unhedged directional position). Also describes two modes (single-market and basket) with appropriate use cases.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint) by detailing safety fields, compatibility warning scenarios, temporal alignment, and skipped counters. It fully discloses behavior and limitations.

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: a clear initial summary, followed by modes, response structure, and safety fields. Every sentence adds value, though it could be slightly more concise.

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

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

Despite lacking an output schema, the description thoroughly covers input parameters, response format (leg-by-leg prices, matched spread), safety fields, and temporal alignment. It provides all necessary context 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?

Schema coverage is 100%, and the description adds significant meaning: listing macro shortcuts for topic, explaining that explicit tickers override mapped sides, and clarifying the role of each parameter.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue spreads.

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 two modes (topic and explicit) and warns that most pre-mapped topics return compatibility warnings, implying limited tradeability. It provides context on when the tool is useful but does not explicitly compare to 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 indicate read-only and idempotent behavior. The description adds that the tool returns attribute rows and geometry, and notes SQL-like query capabilities, providing useful behavioral context beyond annotations.

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

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

The description is two sentences: first states purpose and lists parameters, second gives a concrete usage tip. Every sentence adds value, no wasted words.

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

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

Given the tool's simplicity (6 parameters all documented) and no output schema, the description adequately covers return content and usage. Could mention pagination details or coordinate system, but overall complete.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description reinforces parameter usage (e.g., 'SQL-like where') but does not add significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool queries an ArcGIS Feature Service/Map Service layer by URL, mentions the primary parameters (where, out_fields, etc.), and distinguishes from sibling tools 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 useful usage example ('where="1=1" + out_fields="*" to sample') but does not explicitly state when to avoid using this tool or mention alternatives for other use cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. Description adds value by noting scope (per identifier) and pairing with remember/forget, but no additional behavioral traits beyond annotations.

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

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

Three sentences, front-loaded with action, no wasted words. Every sentence adds necessary context.

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

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

Complete for a simple retrieval tool with one optional param and no output schema. Covers behavior, scoping, and sibling relationships.

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

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

Schema coverage is 100% and description explains key parameter behavior (omit to list all) with examples, adding meaning beyond the schema.

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

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

Clearly states the tool retrieves a value saved via remember or lists all keys if key omitted. Uses specific verb-resource combination (retrieve/list saved values) and is distinct from siblings like remember and forget.

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

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

Explicitly describes when to use (look up stored context) and provides examples. Sibling tools (remember, forget) imply when not to use, but no direct exclusion statements.

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 claims the tool can 'flag returned events read' via mark_read, which modifies state, directly contradicting the annotation readOnlyHint=true. Per rules, score 1 for contradiction.

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

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

The description is four sentences, each adding critical information: purpose, return details, filtering, mark_read behavior, and polling suitability. No superfluous content; front-loaded with verb.

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 5 parameters and no output schema, the description explains return fields, filtering, and mark_read effects. It lacks mention of pagination or ordering but is mostly complete.

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

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

With 100% schema coverage, baseline is 3. The description adds value by providing an example type ('sec_8k') and clarifying that 'since' expects an ISO timestamp, enhancing parameter understanding beyond the schema.

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

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

The description begins with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It specifies return fields (source, citation_uri, raw payload) and filtering options, making the purpose distinct from sibling tools like list_subscriptions.

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

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

The description advises that 'Polls work fine' and provides an alternative URL for scripts/dashboards, giving usage context. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral details: fan-out to multiple sources, GDELT→GNews fallback, and soft-fail for patents due to sunset. No contradiction with annotations.

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

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

Description is well-structured with examples and fallback details. It is longer but efficient, with every sentence adding value. Could be slightly more compact but still clear.

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

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

Given the tool's complexity (multiple sources, fallback logic, parameter nuances), the description covers all necessary aspects. No output schema exists, but it describes return structure (grouped changes, total_changes, URIs). Fully informative for an agent.

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

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

Schema coverage is 100%, but the description adds significant context: explains 'since' accepts ISO date or relative shorthand, 'value' can be ticker or CIK, and recommends '30d'/'1m' for monitoring. Goes beyond what the schema provides.

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

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

The description clearly states it provides a change feed for a company in a time window, covering SEC filings, news, and patents. It distinguishes itself from sibling 'entity_profile' by contrasting dynamic vs. static 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?

Explicitly gives example queries, explains when to use (e.g., 'what's new with X'), and when to use 'entity_profile' instead. Also provides usage tips for the 'since' parameter.

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

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

The description adds valuable behavioral context beyond annotations: it specifies that storage is key-value scoped by identifier, and differentiates persistence for authenticated users (permanent) vs anonymous sessions (24 hours). The annotations already indicate idempotentHint=true (safe to overwrite) and destructiveHint=false, and the description reinforces this with no contradictions.

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

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

The description is concise at 5 sentences, front-loading the core purpose in the first sentence. Each sentence earns its place: the first states function, the second gives usage context, the third provides examples, the fourth explains scoping, and the fifth links to sibling tools. No wasted words.

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

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

Given the tool's simplicity (2 required parameters, no output schema), the description covers key aspects: what it stores, when to use, persistence details, and relationships to sibling tools. It lacks explicit mention of return value (e.g., success confirmation), but since the tool is idempotent and likely silent, this is a minor gap. Overall, it is nearly complete for an agent's needs.

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 'key' and 'value'. The description provides examples of key naming conventions (e.g., 'subject_property', 'target_ticker') but does not add new semantic constraints or details beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to save data for reuse across conversations or sessions. It specifies the verb 'save' and the resource 'data', and provides concrete examples (resolved ticker, target address, user preference). It also distinguishes from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

The description gives explicit guidance on when to use the tool: 'when you discover something worth carrying forward' so you don't have to look it up again. It also tells when not to use alternatives by mentioning that it should be paired with 'recall' for retrieval and 'forget' for deletion, thus setting clear boundaries.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.) by revealing that each call cascades through several internal lookup endpoints and describing the return structure (e.g., for company: ticker, CIK, company_name, citation URI; for drug: RxCUI, ingredient, brand, citation URI). This informs the agent about potential latency and output format. 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 moderately long but well-structured, with the most critical information (purpose, when to use, supported types) at the beginning. Every sentence contributes meaningful detail (returned fields, internal cascading). Minor redundancy could be trimmed, but overall it is 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 the tool's complexity (multiple entity types, internal cascading lookups) and the absence of an output schema, the description fully covers what the tool does, what it returns for each type, and how it handles disambiguation. An agent has all necessary information to use it correctly without additional context.

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

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

The input schema already provides descriptions for both parameters (type and value). The description adds value by offering concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying that for company type the tool accepts ticker, CIK, or name and auto-disambiguates. This enriches the semantic understanding beyond the schema's enum and description.

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

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

The description clearly states that the tool resolves a user-spoken name to a canonical/official identifier. It provides specific examples ('ticker', 'CIK', 'RxCUI') and a usage directive ('Use FIRST whenever you have a name but need an ID'), which distinguishes it from sibling tools that operate on entities already identified.

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

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

The description explicitly states when to use the tool ('when you have a name but need an ID') and lists supported entity types ('company', 'drug') with inputs. While it does not explicitly state when not to use it or mention alternatives, the context is clear enough for an agent to decide. The absence of exclusions is noted but not detrimental.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing that the tool probes each entity with ai_visibility_check, ranks by score, and returns scores, confidence, and signal density. This gives the agent a clear picture of 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?

Two sentences efficiently convey the core function and a concrete use case. No redundant information, every sentence contributes meaning. Structure is front-loaded with the primary action, then output and context.

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

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

Given no output schema, the description adequately describes the return (ranked list with per-entity score, confidence, signal density). It also mentions optional inputs like models and context, covering necessary context for agent usage. The description is complete for a tool with fully documented parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for the entities parameter by stating the first entry is treated as the 'subject' for narrative, which is not in the schema. This helps the agent understand parameter ordering importance. Other parameters are adequately described in schema, so overall value is above baseline.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking, and surfacing most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-presence focus and ranking output.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and implies when to use it (multiple entities, compare AI presence). However, it lacks explicit guidance on when not to use (e.g., for single entity use ai_visibility_check instead) or mention of alternatives. Still, the context is clear for typical 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?

Discloses composite nature, API fan-out, partial failures with 5-30s delay, and graceful degradation. No contradiction with annotations (readOnly, idempotent).

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

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

Front-loaded with main purpose, but lengthy. Each sentence adds value; could be slightly trimmed but still 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?

Covers input, output shape (summary fields, details, links), ecosystem limitation, and failure handling. No missing context for agent to use correctly.

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

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

Schema coverage is 100% but description adds value: clarifies scoped packages accepted, version defaults to latest. Adds meaning beyond schema.

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

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

Clearly states it's a composite check for evaluating npm packages, with specific use cases. Distinguishes from siblings via domain specificity.

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 ('is X safe/popular/small' or cost question) and when not to use (other ecosystems should use deps.dev directly).

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the return structure and the scope (Berks County GIS), providing behavioral context beyond annotations.

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

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

The description is a single, information-dense sentence with no wasted words. It is front-loaded with the main action and efficiently covers purpose, return, and next steps.

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 low-complexity metadata search tool, the description covers core functionality, return fields, and post-processing steps. It omits explicit mention that only metadata is returned, but this is implicit. Sufficient for the context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by contextualizing parameters with examples and domain grounding, slightly above baseline.

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

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

The description clearly states the tool searches Berks County GIS open geospatial datasets by keyword, specifies examples, and differentiates from siblings by mentioning 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 clear usage context (keyword search) and directs to sibling tools for further actions. It includes keyword examples but could explicitly state when not to use this tool or mention alternatives beyond query_layer and layer_info.

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 behavioral details beyond annotations: uses BGE-base-en embeddings with cosine over 500-char overlapping windows, 200K char limit with truncation flagging, and returns offsets for verification. 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?

Two sentences that front-load the core function, then efficiently cover use case, technical details, and pairing. Every sentence earns its place with no waste.

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 (passages with offsets and similarity scores), technical implementation, limits, and pairing with a sibling tool. Fully adequate for an AI agent to understand capabilities.

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 enriches semantics: specifies max chars for text, natural-language query examples, default limit=5, and explains how limit works. Adds value without being redundant.

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

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

Clearly states it performs semantic search inside a fetched record, specifying the use case (large documents) and distinguishing from sibling ask_pipeworx_grounded by describing its role as a complementary tool.

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

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

Explicitly says when to use ('when record is too big to cram into the prompt'), mentions pairing with ask_pipeworx_grounded, and implies it saves context. Lacks explicit when-not to use, but context is clear.

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

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

Beyond annotations (readOnlyHint=false, etc.), the description provides extensive behavioral details: OAuth requirement, one-time webhook secret, auto-disable after 10 webhook failures, SMS rate limit (10/day), and return value ('Returns the new subscription id'). This is rich context for safe usage.

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

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

The description is relatively long but every sentence adds value, covering purpose, auth, types, parameters, and delivery nuances. It is front-loaded with the main action. Could be slightly more structured, but 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 the tool's complexity (3 params with nested objects, multiple types, delivery channels) and no output schema, the description is thoroughly complete. It covers auth requirements, type-specific parameter formats, delivery configurations, rate limits, error handling (auto-disable), and return value.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining parameter formats per type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and delivery channel details (e.g., 'http: only; localhost/private hosts rejected'). This goes beyond the schema's short 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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb 'Create' and the resource 'subscription.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by detailing what a subscription entails.

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 specifies prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also implies usage context by listing supported types and delivery channels, and hints at alternatives like 'recent_alerts' for pulling from the feed. However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that it returns example questions drawn from the live catalog, detailing the output structure beyond the annotations.

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

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

The description is front-loaded with common user queries and is well-structured with a list of categories. It is somewhat verbose but efficiently conveys all necessary information 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?

Despite lacking an output schema, the description comprehensively explains the return format (category-bucketed examples with tool+argument shapes). Combined with rich annotations, it provides sufficient context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with a single optional parameter. The description explains the topic parameter's allowed values and effect (focus on a specific area), which adds semantic context beyond the schema's generic description.

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

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

The description clearly identifies the tool as the onboarding entry point for new agents, returning category-bucketed example questions with tool+argument shapes. It specifies the exact purpose and distinguishes it from siblings by positioning it as the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly states when to use ('Use this FIRST when you do not yet know...') and how to invoke it (no args or topic param). Lacks a direct when-not-to-use, but the context implies it's for onboarding only, not for follow-up queries.

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

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

Annotations indicate destructiveHint=false and idempotentHint=true, and the description adds context: ownership enforcement and that the row is deactivated (not deleted), preserving historical events. This goes 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?

Two sentences with no wasted words. The purpose is front-loaded, and every sentence adds value (purpose, ownership, side effect).

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: purpose, constraints, and side effects. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% for the single parameter 'id', which is described in the schema as 'Subscription id (uuid) returned by subscribe.' The description adds little beyond mentioning 'by id', 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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and adds detail about deactivation rather than deletion.

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

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

The description provides guidance on usage by stating ownership enforcement ('you can only cancel your own subscriptions') and explaining the deactivation behavior. However, it does not explicitly compare with alternatives or mention when not to use.

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

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

The description adds significant behavioral detail beyond annotations. It lists the return verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported) and mentions extracted structured form, actual value with pipeworx:// citation, and percent delta. It also notes efficiency gain by replacing multiple calls. Annotations already mark it as readOnly, idempotent, and non-destructive, and the description aligns perfectly.

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 efficiently structured with front-loaded example patterns, a clear use statement, domain constraints, output details, and an efficiency note. While slightly lengthy, every sentence serves a purpose. It is well-organized and avoids 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?

With no output schema, the description thoroughly explains the return values (verdict types, structured form, actual value, citation, percent delta). It also specifies the data source and scope. For a single-parameter tool, this is highly complete and covers all necessary aspects for an agent to understand its behavior and outputs.

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

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

The schema already describes 'claim' with 100% coverage. The description adds value by explaining the format of the claim (natural language factual claim) and providing concrete examples ('Apple's FY2024 revenue was $400 billion'). This helps the agent understand the expected input type and scope.

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: natural-language claim verification against authoritative sources. It provides multiple example queries ('Is it true that…', 'fact check') and specifies the domain (company-financial claims for public US companies). This distinguishes it from sibling tools like deep_research or bet_research.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also sets clear constraints by noting that v1 supports company-financial claims via SEC EDGAR + XBRL, implying limitations to financial claims about public US companies. While not listing exclusions explicitly, the context is well-defined.

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