Arcgis Raleigh

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. Description adds valuable behavioral details: scoring range 0-100, per-model response structure (score, confidence, signals, raw_response), combined view, and cost implications (workers-ai free, Anthropic BYO key). 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 well-structured sentences: first sets purpose and default, second adds model option and return structure. Every sentence adds value with no fluff. Efficient and clear.

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

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

No output schema, so description fully covers return values: per-model object with score, confidence, signals, raw_response, plus combined view. Also covers all parameters and typical use cases. Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains entity with examples, clarifies models default and when _apiKey is needed, and describes context as optional disambiguation. Exceeds baseline by providing usage context for each param.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it 0-100. It specifies the verb 'probe', resource 'LLMs for knowledge about a business/brand/product/topic', and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic brand visibility with per-model scoring.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Also explains when to use the default model vs Anthropic (requires _apiKey). Lacks explicit when-not-to-use but context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, providing a strong safety profile. The description adds value by explaining internal routing ('Routes the question to the right one of 4,552 tools across 1160 verified sources') and return format ('structured answer with stable pipeworx:// citation URIs'), which goes beyond annotations without contradicting them.

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

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

The description is somewhat lengthy but well-structured. It front-loads the key message ('PREFER OVER WEB SEARCH') and then systematically covers domains, examples, and guidance. Each sentence serves a distinct purpose, though there is minor repetition (e.g., 'START HERE for most questions' echoes earlier preference).

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 absence of an output schema, the description compensates by stating it returns 'structured answer with stable pipeworx:// citation URIs.' It covers when to use, behavioral traits, parameter usage, and examples. The tool is simple with one required parameter and strong annotations, so the description provides full necessary context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples of questions and explaining that the tool 'fills arguments' automatically. This helps the agent understand what to input in the question parameter and how the tool processes it, adding semantic context beyond the schema's property descriptions.

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

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

The description clearly states that the tool routes questions to a large set of verified sources and returns structured answers with citations. It lists specific domains (SEC filings, FDA data, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' and resource 'Pipeworx' are precise, making the purpose unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use the tool (e.g., for factual questions about real-world entities). It gives examples and specifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad questions). It also implies when not to use it by noting that breaking news is already handled.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral traits: hallucination-resistant, uses only tool result, returns explicit refusal reasons, and costs an extra LLM call. No contradictions.

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

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

The description is a single dense paragraph but front-loaded with key purpose and usage. It is well-structured despite length; every sentence adds value. A slight reduction could improve conciseness, but it's 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 (selecting from 4552 tools), rich annotations, and no output schema, the description fully explains return format, refusal reasons, and trade-offs with sibling. No gaps identified.

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

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

Schema coverage is 100% with all parameters well-described. The description adds that aliases (q, text, etc.) all map to 'question' and that 'question' accepts natural language, but this is mostly redundant with the schema. Minimal added value beyond 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 that this is a 'hallucination-resistant answer mode for high-stakes reads', specifying the verb 'extract answer' and the resource 'tool result'. It distinguishes from the sibling ask_pipeworx by noting the extra LLM call and exact usage contexts.

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

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

Explicitly provides when-to-use (high-stakes reads, when answer will be quoted/cited/acted on, must not invent facts) and when-not-to-use (prefer ask_pipeworx for casual lookups). Also lists refusal reasons, giving clear alternatives.

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

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

The description goes far beyond annotations, detailing internal resolution, classification, fan-out parallelism, response shapes, edge cases (low-confidence, closed markets, wide spreads, resolution-rule risk), and safety mechanisms. It aligns with readOnlyHint, idempotentHint, and destructiveHint, adding critical context like market_match_confidence inspection and blocking paths.

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 overly long, containing repetitive examples and sections that could be condensed. The first sentence front-loads purpose well, but the density makes it harder to parse quickly. Every sentence earns its place in terms of information, but conciseness is compromised.

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 (multi-step fan-out, classification, various data sources), the description covers all necessary aspects: input formats, resolution process, response structure, edge cases, and safety. No output schema exists, but the description compensates by detailing response shapes (result.market, result.analysis, etc.). It is complete 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%, so baseline is 3. The description adds meaning beyond schema by elaborating on depth parameter with fan-out examples and explaining include_raw trade-offs (response size vs full payload). It reinforces schema descriptions but does not introduce new parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb ('Research') and resource ('Polymarket bet'). Examples of inputs and outcomes (evidence packet, market-vs-model comparison) leave no ambiguity. It differentiates from sibling tools by focusing on Polymarket bets with data fan-out.

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 specifies when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides detailed fan-out examples for various bet types, helping agents decide when this tool is appropriate. While not naming alternatives, the guidance is thorough and contextual.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. The description adds valuable context: it specifies the exact financial metrics pulled (revenue, net income, cash, debt) from SEC EDGAR/XBRL, handles off-calendar fiscal years, and explains data sources for drugs. No contradictions.

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

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

The description is a single dense paragraph but is well-structured: it starts with usage trigger phrases, states a strong preference, explains type-specific output, and concludes with efficiency claims. Every sentence adds value without repetition.

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 tool's complexity (two entity types, multiple data sources, sorting, citations), the description covers all essential aspects: what it does, when to use, input parameters, return data, sorting behavior, and efficiency. No output schema exists, so the description sufficiently describes return values.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning beyond the schema by detailing what data each type returns (e.g., 'latest 10-K revenue + net income + cash + long-term debt' for companies, 'FAERS adverse-event counts, FDA approval counts' for drugs). This elevates the score.

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 defines the tool as a side-by-side comparison for 2–5 companies or drugs in one parallel call, using clear query phrases like 'compare X and Y' and 'X vs Y.' It explicitly distinguishes this from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' provides concrete example queries, and explains the different data returned for company vs drug types. This gives strong guidance on when and how to use the tool over 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?

Adds substantial behavioral context beyond annotations: account sign-in required, paid tier for 'thorough', parallel execution across 4,552 tools, expected 15-60s latency, return format with verbatim evidence + confidence + source + gaps[], and limitation that non-structured topics yield empty gaps. No contradiction with annotations (readOnlyHint, openWorldHint, etc.).

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. It is front-loaded with the critical requirement of account sign-in and depth restrictions. Minor redundancy could be trimmed (e.g., explaining decomposition twice), but overall it is well-structured and informative.

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

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

Given the tool's complexity, lack of output schema, and numerous sibling tools, the description is exceptionally complete. It covers authentication, timing, use cases, limitations, return format, and alternatives. No gaps remain for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with descriptions for both 'question' and 'depth'. The description adds meaning: depth enum values map to number of facets (quick=3, standard=5, thorough=8) and 'thorough' requires a paid plan. It clarifies that the question should be in natural language and that broad/multi-part questions are intended.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and decomposes questions into facets. It distinguishes itself from sibling tools like ask_pipeworx (single lookup) and explicitly says it is not open-web search. The verb 'researches' and resource 'structured data sources' are specific and unambiguous.

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

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

Provides explicit guidance on when to use: 'broad/multi-part questions over structured data' and when not: 'BREAKING or colloquial CURRENT-NEWS' and single lookups. Directly names alternatives: 'use ask_pipeworx instead' for certain cases, and notes account requirements including paid plan for 'thorough' depth.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are fully consistent. Description adds that each result is ready to call directly, no second schema lookup needed, enhancing transparency without contradiction.

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

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

Concise single paragraph that front-loads purpose and includes usage guidance. Slightly dense but efficient; 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?

Covers purpose, usage, return format, and behavior for a discovery tool. Could mention pagination or error handling, but overall sufficient for the tool's role.

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

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

Schema coverage 100% with good descriptions. Description adds examples of natural language queries and explains the limit parameter's default and max, providing useful usage context beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists many example domains, and distinguishes itself from siblings by being the discovery tool to call first.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools.' Provides clear context 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 indicate idempotent, read-only, and non-destructive behavior. The description adds context about fanning out across multiple data sources, soft-failures for patents, and explicit return fields (cik, filings, fundamentals, patents, news, LEI). No contradictions.

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

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

The description is well-structured with example queries upfront, followed by usage preference, return details, and parameter constraints. While lengthy, every sentence adds value; minor redundancy could be trimmed.

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

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

Despite no output schema, the description comprehensively lists all returned components (cik, company_name, filings, fundamentals, patents, news, LEI) and documents limitations (patents sunset, name not supported). Fully adequate for tool 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?

Schema coverage is 100% with both parameters described. The description adds value by explaining the 'type' enum limitation (only 'company' supported) and clarifying that 'value' accepts ticker or zero-padded CIK, not names. 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?

The description clearly defines the tool as a 'full cross-source profile of a US public company in ONE parallel call,' providing specific verb-resource pairs and distinguishing from chaining single-pack lookups. It contrasts with sibling tools like resolve_entity for name resolution.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing users to resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description confirms delete behavior but adds no additional behavioral context beyond what annotations and schema offer.

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

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

Two concise sentences, front-loaded with the core purpose, and every sentence serves a clear purpose without 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?

Given the simple single-parameter tool, with annotations covering safety and idempotency, the description is complete. No output schema needed, and the use cases are well-stated.

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 parameter 'key' is already described in schema. The description only reiterates 'by key', adding no new semantic value.

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

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

The description clearly states the action (delete), the resource (memory), and the method (by key). It distinguishes from sibling tools by mentioning 'remember' and 'recall' in the usage guidance.

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

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

Explicitly provides three clear scenarios for when to use this tool (stale context, task done, clear sensitive data). However, it does not explicitly state when not to use it, though the positive guidance is strong.

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

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

Annotations already indicate safe, idempotent behavior. The description adds that the tool fetches the page, extracts metadata, and produces a text file, filling in behavioral details like external HTTP requests and output format.

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

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

The description is three sentences, front-loading the core action and output. Every sentence is necessary, 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 no output schema, the description adequately describes the output as 'single text blob ready to drop at site-root/llms.txt'. It covers fetching, extraction, and intended use, making it 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%, so description adds limited value. It clarifies the 'url' parameter with an example and reiterates 'max_links' defaults, but does not provide additional semantic depth beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate), the resource (llms.txt), and the purpose (AI crawler indexing). This distinctively separates it from sibling tools.

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

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

The description lists concrete use cases like 'getting a client's site indexed' and 'auditing competitor visibility', guiding when to use. It lacks explicit exclusions or alternatives, but the use cases are specific 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 declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds valuable behavioral context by specifying what information is returned (fields, geometry, count, capabilities) and implies read-only operation without contradiction.

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

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

The description is a single sentence of 20 words, very concise and front-loaded with the verb and resource. Every word adds value, with no redundancy or unnecessary detail.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, input, and output. It lists all key return elements, leaving no significant gaps in understanding.

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

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

Schema coverage is 100% for the single 'url' parameter, and its description provides an example format. The tool description adds no further semantic detail beyond 'by url', so the baseline score of 3 applies.

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

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

The description uses a clear verb 'Get' and specifies the exact resource: 'ArcGIS Feature/Map Service layer's schema'. It lists concrete outputs: fields, geometry type, record count, capabilities. This distinguishes it from sibling tools like 'query_layer' which likely query data.

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

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

The description implicitly indicates the tool's purpose (getting schema) but does not explicitly state when to use it versus alternatives like query_layer. No exclusions or prerequisites are mentioned, leaving the agent to infer context from sibling 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 indicate read-only, idempotent, non-destructive behavior. The description adds context beyond annotations by specifying that it returns only active subscriptions by default and listing the returned fields, which helps the agent understand the output without needing to guess.

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: two sentences with no extraneous information. The first sentence states the purpose and key output fields; the second provides usage guidance. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and rich annotations, the description covers purpose, output fields, usage context, and parameter behavior. No output schema exists, but the description adequately describes return fields. It feels complete.

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

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

The schema coverage is 100% (one parameter with a clear description). The description does not add additional semantics beyond what the schema provides, except that it mentions 'active subscriptions' by default, which aligns with the parameter. 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 resource ('subscriptions') and action ('list'), and specifies the returned fields. It implicitly distinguishes from siblings like 'subscribe' and 'unsubscribe' by suggesting use cases for reviewing monitoring and finding IDs to cancel, though it does not explicitly name alternatives.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This effectively tells when to use the tool, but it does not explicitly state when not to use it or mention alternative tools.

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

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

Discloses rate-limiting (5 per identifier per day), free usage, and that feedback is reviewed daily, affecting the roadmap. Adds value beyond annotations, which lack such details.

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

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

Single paragraph with no wasted words. Front-loaded with purpose, then usage, then behavior. Every sentence earns its place.

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

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

Despite no output schema, covers input semantics, usage conditions, and behavioral constraints. Fully sufficient for an 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?

Enriches schema descriptions with practical advice: explains enum choices, instructs on message format (1-2 sentences, 2000 chars), and clarifies that context is optional. With 100% schema coverage, this adds significant value.

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

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

Description clearly states it is for sending feedback about bugs, missing features, or praise. Uses specific verbs and distinguishes from other tools by focusing on feedback collection.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and free usage, providing comprehensive guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it's self-aggregating from CF analytics-engine, no PII, and cached 5min-1h. No contradiction with annotations.

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

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

The description is concise, front-loaded with the core function, followed by structured use cases, then technical details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete. It explains the return data (top tools, top packs, total call volume) and caching behavior. No gaps.

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

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

Schema coverage is 100% with one parameter fully described. The description adds meaning beyond the schema by explaining the window option semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand.'). This adds practical guidance.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It specifies the verb 'returns' and the resource 'Pipeworx trending data'. It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending/aggregate data.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains the window options' implications. While it doesn't explicitly state when NOT to use, it provides clear context for when this tool is appropriate.

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

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

Disclosures behavioral details beyond annotations: semantic anchor with Jaccard similarity threshold, partition placeholder filter, fill check against live order book. No contradictions with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Well-structured with clear sections and examples. Every sentence provides essential information; no redundancy. Long but necessary given 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?

Comprehensive coverage of tool behavior, input modes, constraints (similarity, placeholder filter), and return structure (opportunities, partition_check, fill_check). Adequate despite lack of output schema.

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

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

Schema coverage is 100%, and description adds significant context: examples of event slugs and topic questions, explanation of how each mode operates, and additional constraints. Enhances understanding beyond raw 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes between three modes (trending scan, event, topic) and specific inputs. Differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly instructs when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Provides recommendations and warns when not to trade (realizable_edge_pp <= 0). Mentions alternative tool for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds extensive behavioral details: caching 1h, response structure with segments and diagnostics, edge calculation methodology, knob effects, and market move warnings. 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 long but well-structured with numbered sections and bullet points. It front-loads the main purpose and then dives into details. Some redundancy exists, but it is organized for easy scanning. Slightly verbose but earns its length given the tool's complexity.

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

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

The tool has no output schema, 9 parameters, and high complexity. The description covers all behavioral aspects: response segments, diagnostics, caching, filtering logic, and even explains why Fed bets are excluded. It leaves no obvious gaps for an AI agent to understand invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp) and the logic behind min_partition_leg_kelly, surpassing what the schema alone provides. Baseline 3 plus extra 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 it scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using specific verb 'Scan top Polymarket markets and return opportunities'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge detection across multiple model families.

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets', indicating when to use. It mentions three segments and their use cases, but does not explicitly compare to siblings or state when not to use. Clear context for usage.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context: it reads snapshots, computes trends (new/widening/stable/decaying), tracks expired opportunities with lifespan, and explains that snapshot gaps occur on cache misses. It also details the decay computation (daily closes, not intraday). 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 lengthy but every sentence serves a purpose. It front-loads the core concept ('how long has this edge existed and is it shrinking?'), then naturally organizes the response structure (tracked[], expired[], snapshot_dates[]) and closes with limitations. No filler or redundant repetition.

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 lack of an output schema, the description comprehensively explains the three return arrays (tracked, expired, snapshot_dates) with detailed field semantics (first_seen, trend, decay_pp_per_day, lifespan_days). It also covers constraints (history depth bounded by 60-day TTL, snapshot gaps) and algorithmic notes (decay from daily closes). The complexity of time-series analysis is fully addressed.

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

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

The input schema already describes both parameters with 100% coverage (days: default 14, clamp 2-30; window: default '1wk', options '24hr|1wk|1mo'). The description adds minor additional context (days max 30, window relates to snapshot family) but does not significantly augment the schema's meaning. The response description partially compensates by showing how parameters affect output.

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

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

The description uses specific verbs ('answers', 'returns') and clearly identifies the resource ('edge persistence and decay telemetry from daily polymarket_edges snapshots'). It distinguishes itself from generic edge tools by focusing on time-series analysis and trend computation. The detailed explanation of response fields leaves no ambiguity about its functionality.

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 strong contextual guidance—e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'—to help the agent decide when historical persistence matters. It also mentions limits (60-day TTL, snapshot gaps). However, it does not explicitly compare itself to sibling tools like polymarket_edges, nor does it state when to avoid using it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds behavioral context beyond these: describes ladder walking, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about partial fills and directional risk. No contradiction with annotations.

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

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

The description is lengthy (7+ sentences) but front-loaded with the core purpose. Every sentence adds value, covering two modes, return fields, thresholds, and warnings. However, the detailed enumeration of return fields (e.g., 'top_of_book, vwap_fill_price, slippage_pp...') could be condensed. Still, density is justified by complexity.

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

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

Given the tool's complexity (two distinct modes, multiple return fields, no output schema), the description thoroughly explains what the tool does, what it returns, when to use it, and potential pitfalls (e.g., thin_legs, forced_directional_risk). It covers prerequisites and the dominant loss mode, making it complete 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% (all four parameters have descriptions in the schema). The description adds significant meaning: explains side default logic for basket ('auto from partition sum'), interprets size_usd differently for single-market vs basket (spend vs target proceeds vs settlement notional), and reinforces the REQUIRES one of market or event constraint.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges, telling the agent to use this tool before acting on those signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial fills convert arb to unhedged directional position), which helps the agent decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral details: safety fields (compatibility_warning, temporal_alignment, skipped counters) and their meaning, plus that many topics return warnings. This goes beyond annotations without contradicting them.

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

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

Description is moderately long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with core purpose. Every sentence adds value; minor redundancy possible but overall efficient for the complexity.

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

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

Given no output schema, the description explains response contents (leg-by-leg prices, spread, safety fields) sufficiently. Covers edge cases with compatibility warnings and temporal alignment. A full example would improve completeness, but current detail is adequate.

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

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

Schema coverage is 100%, so parameters are documented. The description adds meaning by explaining the two modes, listing exact topic values, and clarifying that explicit tickers override topic-mapped sides. This enhances understanding beyond schema alone.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, which distinguishes it from siblings like polymarket_arbitrage and polymarket_edges that focus on single-venue or other types of analysis. The verb is implied but context is strong.

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 two modes (topic shortcuts and explicit tickers), provides a list of pre-mapped topics, explains when warnings fire, and warns that most pre-mapped topics are not tradeable. Does not directly compare to sibling tools but gives sufficient context for use.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns attribute rows and geometry, providing useful behavioral context without contradiction.

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

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

Two sentences: first covers function and parameters, second gives a practical tip. No fluff, every sentence earns its place.

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

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

No output schema, but description mentions return of attribute rows and geometry. Covers pagination via limit/offset. Could be more explicit about response format, but adequate for a query tool.

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

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

Schema description coverage is 100%, and the description adds value by explaining the URL format and giving examples for where, out_fields, order_by, 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 explicitly states it queries an ArcGIS Feature/Map Service layer by URL, lists key parameters, and links to search_datasets for finding datasets, clearly distinguishing its purpose.

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

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

Provides a concrete usage example ('where="1=1" + out_fields="*" to sample') and implies it should be used after search_datasets, but no explicit 'when not to use' or alternatives.

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

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

Annotations provide readOnlyHint and idempotentHint; description adds value by explaining scoping to identifier and pairing with remember/forget. No contradiction.

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

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

Three sentences, front-loaded with main action, no waste. Every sentence earns its place.

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

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

For a simple tool with good annotations and schema, description covers retrieval, listing, scope, and sibling tools. Complete.

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

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

Schema covers parameter fully; description adds that omitting key lists all saved keys, which is not in schema. Adds useful semantic context.

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

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

Clearly states it retrieves a value saved via remember or lists all keys. Distinguishes from sibling tools remember and forget. Specific verb+resource+scope.

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

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

Gives explicit use cases (look up previously stored context) and mentions scoping. Implies alternatives (remember/forget) but lacks explicit 'when not to use'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description explains the mark_read side effect (flagging events read) and the alternative REST endpoint, which adds context beyond annotations. No contradiction; the side effect is optional and non-destructive.

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

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

The description is a single concise paragraph of 5 sentences. It front-loads the main purpose, then efficiently covers parameters and usage. Every sentence adds value; no redundancy or wordiness.

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

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

The tool has 5 optional parameters, no output schema. The description covers return fields, parameter usage, polling suitability, and an alternative endpoint. It does not specify result ordering or potential parameter conflicts (e.g., mark_read + unread_only). Overall fairly complete for a list 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%, giving baseline 3. The description adds meaning: examples for 'type' (e.g. sec_8k), specifies 'since' as ISO timestamp, clarifies 'mark_read' and 'unread_only' behavior, and notes limit range (1-200). This adds significant value beyond schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies the returned fields (source, citation_uri, raw payload). It distinguishes from sibling tools by mentioning an alternative REST endpoint, but does not explicitly contrast with siblings 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 gives clear usage guidelines: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp). Set mark_read:true to flag returned events read... Polls work fine.' It provides context on when to use parameters and that polling is acceptable, but does not state when not to use the tool or compare with 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 readonly, idempotent, non-destructive. Description adds multi-source fan-out, soft-fail for USPTO, and relative date format support. No contradictions.

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

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

Description is somewhat long but every sentence adds value. Front-loaded with example queries. Could be slightly more structured, but efficient overall.

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 multiple data sources, fallback, and return format (changes, total_changes, URIs) despite no output schema. Could mention pagination or limits, but adequate for complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by providing examples of 'since' values, clarifying that value can be ticker or CIK, and explaining the meaning in 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?

Description clearly states the tool provides a change feed for a company in a time window, with concrete example queries. It distinguishes from sibling entity_profile by contrasting dynamic vs static use.

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

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

Explicitly advises use for dynamic changes and directs to entity_profile for static needs. Also explains fallback behavior between GDELT and GNews. Could be more explicit about when not to use, but the alternative is clear.

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

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

Annotations indicate idempotent and non-destructive behavior. The description adds useful context: storage as key-value pair scoped by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). However, it doesn't mention limits or overwrite behavior explicitly.

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: several sentences, no fluff, front-loaded with the main purpose. Every sentence adds value.

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

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

Given the tool has two required plain-text parameters and no output schema, the description is complete: it covers usage, persistence, pairing with recall/forget, and the distinction between authenticated and anonymous sessions.

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

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

The schema covers 100% of parameters with descriptions. The description adds meaning by providing examples of how keys and values should be used (e.g., 'key: subject_property, value: findings'). This helps the agent understand usage patterns.

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 later reuse across conversations/sessions. It provides specific examples (resolved ticker, target address, user preference) and distinguishes from sibling tools recall and forget.

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

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

The description explicitly says when to use (discover something worth carrying forward) and mentions alternatives (recall, forget). It could be more explicit about when not to use, but the context of persistence is well covered.

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=true, idempotent=true, destructive=false. The description adds substantial context: internal cascading through multiple endpoints, specific return fields (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). No contradictions.

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

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

The description is well-structured with examples first, then usage guideline, then type details. It is slightly verbose but every sentence adds value. It could be more concise while retaining the same 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, the description fully explains return values per type. Parameters are fully covered by schema. The tool's behavior is completely described, including internal cascading lookups, making it self-contained for correct invocation.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains acceptable inputs (ticker, CIK, name for company; brand/generic for drug) and clarifies the output format, compensating for the lack of output schema. This goes beyond the minimal 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 explicitly states the tool resolves names to canonical identifiers, provides clear examples (ticker, CIK, RxCUI), and specifies supported types (company, drug). It distinguishes itself from sibling tools like 'entity_profile' by focusing on ID resolution rather than detailed profiles.

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 directs the agent to 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use guideline. It also explains that the tool replaces multiple manual lookups. However, it does not explicitly mention when not to use or list alternatives among siblings, which would be helpful.

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. Description adds that it probes each entity with ai_visibility_check, ranks, and returns specific fields (score, confidence, signal density), providing operational 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?

Four sentences, front-loaded with core action. Each sentence adds value: comparison scope, probing process, use case, output format. No redundant or extraneous text.

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 adequately explains output (ranked list with per-entity scores, confidence, signal density). Also notes that first entity is treated as subject. Behavioral info is complete with annotations.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description does not add extra parameter details beyond what schema provides; it only restates the context param's purpose minimally. Baseline score applies.

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 compares AI visibility across multiple entities, ranks by score, and surfaces most/least recognized. It differentiates from sibling like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly mentions use case: competitive AI-marketing audits. Implicitly suggests using ai_visibility_check for single-entity checks. Does not state explicit when-not-to-use or alternatives, 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?

Disclosure of graceful degradation: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' Also describes return structure (summary block, per-advisory detail, links, alternative versions). Annotations already indicate read-only, idempotent, non-destructive; description adds behavior details.

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

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

The description is appropriately sized for a composite tool, front-loading the core purpose. Every sentence adds information, though it could be slightly tighter. No redundancy.

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

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

Given the complexity (composite check across two services) and the lack of an output schema, the description provides a thorough overview: lists returned fields (is_latest, license, etc.), explains partial failure behavior, and covers edge cases (scoped packages, default version, ecosystem limitations). Complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages are accepted for 'package' and default behavior for 'version' ('defaults to the latest published version when omitted'). These details go beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'composite should I add this npm package to my project check' fanning out across deps.dev and bundlephobia. It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on npm package evaluation.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and specifies scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version 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 readOnlyHint, idempotentHint, and non-destructive. Description adds value by stating that the output includes name, summary, record_count, owner/org, and url, and hints at the query semantics. 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, no fluff. Front-loaded with purpose and immediately provides actionable information (return fields and follow-up tools).

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, description fully covers return structure and suggests next steps. Includes domain context (City of Raleigh GIS) and examples. No gaps for a search tool with strong annotations.

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

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

Schema has 100% coverage with descriptions for all parameters. Description does not add new parameter details beyond 'by keyword' which matches the query parameter. No extra constraints or format info.

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

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

Clear verb+resource ('Search City of Raleigh GIS open geospatial datasets') with specific examples of content (parcels, zoning, etc.) and explicit return fields. Differentiates from sibling tools like query_layer/layer_info which operate on the returned url.

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 instructs to pass the returned Feature Service url to query_layer/layer_info, guiding the chaining workflow. Does not specify when not to use, but context is clear from domain-specific datasets.

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 details beyond annotations: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flag, returns offsets. 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 purpose first, then usage, then technical details. Could be slightly shorter but every sentence adds value; no unnecessary words.

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

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

Despite no output schema, description explains return values (top-N passages, offsets, similarity scores). Covers complexity and edge cases (truncation) 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%, but description adds useful context: text max 200K, query as natural-language, limit range 1-20 default 5, which enhances understanding beyond schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K body, article). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining pairing behavior.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded, providing clear alternatives and context.

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

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

The description adds significant behavioral context beyond annotations, including auth requirements, return value, type-specific filters, delivery constraints (email validation, SMS cap, phone verification, webhook HMAC signing, auto-disable on failure). Annotations indicate idempotentHint=true, and the description aligns without contradiction.

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

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

The description is well-structured and front-loaded with the primary purpose. While it is lengthy, every sentence earns its place by providing essential details. Minor improvements could tighten some phrasing, 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 subscription types, delivery channels, auth requirements, and constraints), the description is complete. It covers prerequisites, return values, type-specific parameters, delivery behavior, and error prevention (e.g., phone verification, SMS cap, webhook auto-disable). No output schema, but return value is stated.

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 enriches each parameter with concrete examples and constraints. For instance, it explains sec_8k params with item codes and polymarket_edge with topic details, and delivery options with validation rules. This adds substantial value beyond the schema.

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

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

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

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

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

The description provides explicit context: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It details when to use each subscription type and delivery channel. However, it lacks explicit when-not-to-use guidance or alternatives, though sibling tools are available.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare safety. Description adds context about returning 'category-bucketed example questions' from a 'live catalog,' complementing annotations without contradicting them.

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

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

Single dense paragraph front-loaded with purpose and alternative phrasings. It efficiently covers all key aspects, though slightly more bullet-pointed structure could aid quick scanning.

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

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

Covers what, when, how to use, and what it returns. For a simple onboarding tool with no output schema, it provides complete information including categories and mention of meta-tools.

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

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

Schema coverage is 100%; the description adds examples ('finance', 'pharma') and clarifies that omitting gives full spread, going beyond the schema definition.

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

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

The description clearly states the tool is an 'onboarding entry point' that suggests questions and shows how to call tools. It distinguishes itself from siblings by being 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 says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides calling instructions for no arguments or with a topic. This gives clear usage context.

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

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

Annotations provide readOnlyHint false, destructiveHint false, idempotentHint true, openWorldHint true. Description adds value by clarifying the row is deactivated not deleted, and ownership enforcement. This goes beyond annotations and gives a complete behavioral picture.

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 concise sentences with no wasted words. The main action is front-loaded ('Cancel a subscription by id'), and additional context follows efficiently.

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

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

For a simple one-parameter tool with good annotations, the description is complete. It covers purpose, ownership constraint, and the deactivation behavior, which is sufficient for an agent to understand the tool's effect.

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

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

Schema description coverage is 100% for the single parameter 'id,' and the schema already describes it as a subscription uuid. Description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id,' which is a specific verb+resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

Description provides explicit context: ownership is enforced ('you can only cancel your own subscriptions') and it explains the deactivation approach. It implies when to use (when you own the subscription) but does not explicitly state when not to use or suggest alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the return structure (verdict types, structured form, actual value with citation, percent delta) and data source (SEC EDGAR + XBRL), providing full behavioral transparency.

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

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

The description is well-structured and front-loaded with examples, but somewhat long. Every sentence adds value; minor conciseness improvements possible.

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 (single parameter, no output schema), the description fully covers purpose, usage, return values, and domain, making it complete for an AI agent to decide when and how to use.

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

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

The schema has 100% coverage for the single parameter 'claim' with a clear description. The tool description adds examples, domain scope, and return details, significantly enriching the parameter's semantics.

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

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

The description explicitly states the tool's function as natural-language claim verification against authoritative sources, provides example queries, and distinguishes it from siblings by noting it replaces 4-6 sequential calls.

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

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

It clearly states when to use ('whenever the agent needs to check factual correctness of a user's statement') and implicitly when not to use (only company-financial claims for v1). Could explicitly state excluded domains.

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