Arcgis Dc

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

Beyond the readOnly/idempotent annotations, the description discloses the free default model, the BYO key arrangement for Anthropic ('you pay Anthropic directly'), and a return-structure preview. 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?

Three focused sentences cover purpose, auth/cost behavior, return format, and use cases. Every sentence earns its place without fluff.

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 read-only probe tool with rich annotations and full schema coverage, the description is near-complete. It covers the return shape and use context; a minor omission is error/limit behavior, but overall sufficient.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds the specific model name 'Workers AI Llama-3.3-70b' and cost implications, but most parameter details (free default, _apiKey requirement) are already in the schema, so added value is marginal.

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

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

The description opens with a specific action ('Probe one or more LLMs...') and clearly defines the output (visibility score 0-100 per model). It clearly differentiates the tool's focus on AI visibility, though it doesn't explicitly contrast with sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that signal when to deploy. It does not mention alternatives or when not to use it, so no exclusions are given.

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

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

The description adds context beyond the annotations by explaining that the tool routes to 5,462 tools across 1419 sources, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier. This enriches the readOnly/openWorld/idempotent hints without contradiction, though it could mention potential rate limits or cost.

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?

Though lengthy, the description is well-structured and front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'). It packs in trigger phrases, examples, alternative escalation paths, and a note on news routing, with no filler; every sentence serves a distinct purpose.

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

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

For a meta-tool with no output schema, the description covers all necessary aspects: what it does, when to use it, what input to provide, what output to expect (structured answer with citation URIs), and how it fits with siblings. It is complete 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?

The schema already provides 100% coverage with aliases, so the baseline is 3. The description adds value with real-world examples of questions (e.g., 'current US unemployment rate', 'patents Tesla was granted last month') and clarifies that natural language is accepted, which helps an agent formulate inputs effectively.

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 answers factual questions by routing to the right tool among thousands and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its 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 gives explicit when-to-use advice: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' with trigger phrases and concrete examples. It also specifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions), providing clear exclusion criteria.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that candidate routing improvements may be enabled live and that no candidate is currently active. It also clarifies that this is a full working router with no fallback, adding behavioral context not already present in 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 four sentences that front-load the core identity ('Beta version of ask_pipeworx') and then explain the experimental nature and usage. While slightly verbose, each sentence contributes value without redundancy, earning a 4 rather than a 5.

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

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

The tool is a simple single-input router. The description covers purpose, usage, current status, and experimental comparison. The lack of an output schema is partially addressed by mentioning the same response shape as ask_pipeworx, though the exact response format is not detailed. This is sufficient given the tool's simplicity.

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

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

The input schema fully documents all six parameters as aliases for the single 'question' field. The description adds no parameter-specific information, so the schema carries the semantic load. Given 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself by being the experimental edge with candidate routing improvements, making it distinct from the stable ask_pipeworx sibling.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' providing direct usage guidance. It also explains the experimental comparison process and the current fallback state, clarifying when this tool is appropriate versus the stable alternative.

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

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

Goes far beyond the readOnlyHint annotation by explaining the extraction mechanism ('using ONLY what the tool result contains'), detailing the success and refusal response shapes, listing specific refusal reasons, and noting the extra LLM call cost. This is rich behavioral context not available from 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?

Although long, every sentence serves a purpose: summary, mechanism, response format, use case, and cost trade-off. The information is dense but well-structured, front-loaded with the core value proposition, and contains no redundant or filler content.

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

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

Despite having no output schema, the description thoroughly explains the return shape, refusal conditions, use cases, and comparison to the sibling tool. Considering the tool's complexity and the absence of an output schema, the description is fully self-contained and 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 covers all parameters (100% coverage) with a clear description of the 'question' field and its aliases. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

Clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource. Distinguishes itself from the sibling ask_pipeworx by describing the same routing but adding grounded extraction. The purpose is 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?

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and contrasts with 'prefer ask_pipeworx for casual lookups.' This gives clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, but the description goes far beyond: it details resolver contracts, status values, suppression of analysis fields on low-confidence matches, market_closed_or_inactive blocking, wide-spread illiquidity warnings, and resolution-rule risk (refund_50_50 etc.). It also explains news fallback behavior. 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 long but extremely well-structured with clear section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and each section adds necessary invocation-relevant detail. It is front-loaded with purpose and use cases. A small amount of redundancy exists (schema examples repeated), so not a perfect 5.

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

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

There is no output schema, so the description must explain return values and error/edge behaviors itself. It does this exhaustively: response shapes for result.market/analysis/evidence, resolver fields, parent-event structure, news fallback fields, and blocking statuses. The coverage is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100%, and the schema already explains market, depth, and include_raw with examples. The tool description reinforces these (e.g., accepted market formats, quick vs thorough) and adds fan-out examples, but does not meaningfully expand parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's scope (resolving markets, classifying bets, fanning out to data packs, returning evidence + comparison) and differentiates it from siblings like polymarket_edges and polymarket_arbitrage by focusing on full research/evidence gathering rather than just pricing or edge calculation.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking behaviors for low-confidence matches and closed markets. However, it does not name alternative tools or state when NOT to use this tool, so it misses the exclusion part of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral detail: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format with citation URIs. This far exceeds what annotations alone provide with no contradiction.

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

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

The description is a single dense paragraph but every sentence contributes value: trigger phrases, usage preference, data source details, sorting behavior, and output. It is slightly long (~180 words) for a tool description, but there is no fluff; the structure front-loads the most important usage guidance.

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

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

Despite no output schema, the description fully explains what the tool returns (paired data + citation URIs), how results are sorted, and key edge cases (off-calendar fiscal years). It covers type-specific behavior and limits (2–5 entities), making the tool's behavior clear even in complex scenarios.

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, giving a baseline of 3. The description goes further by explaining the meaning of each type ('company' pulls latest 10-K figures, 'drug' pulls FAERS/trial counts) and providing concrete examples for values (['AAPL','MSFT'], ['ozempic','mounjaro']). This adds contextual semantics beyond the schema.

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

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

The description uses a specific verb+resource ('side-by-side comparison of 2–5 companies or drugs') and immediately distinguishes itself from sibling tools like entity_profile by emphasizing a single parallel call. It also lists trigger phrases ('which is bigger', 'rank these companies') that make the purpose unmistakable.

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

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

The description explicitly states when to use it: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear alternatives (sequential lookups) and even quantifies the benefit ('Replaces 8–15 sequential lookups'). The type-specific behavior further guides selection between company and drug comparison.

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

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

Annotations already mark readOnly, openWorld, idempotent, and non-destructive, and the description adds a wealth of behavioral context: account/paid-plan requirements, parallel tool routing, gap reporting, contradiction flags, semantic excerpting, citation guarantees, and latency expectations. It even clarifies that openWorldHint here means structured sources, not web search, which preempts a likely misconception.

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 every sentence carries operational or selection value—auth caveats, tier limitations, latency, alternative tools, and result-shape details all earn their place. It is somewhat run-on and could be bulleted, but it is not padded.

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

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

With no output schema, the description takes on full responsibility for explaining the return value, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers edge cases like topics not in the catalog, making this a complete operational picture.

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

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

Schema coverage is 100%: both `question` and `depth` have descriptive schema text including enum behaviors and defaults. The description enriches the tool-level behavior but does not add meaning to the parameters beyond what the schema already states, so the baseline 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 opens with a specific, multi-clause statement of what the tool does: grounded multi-source research across Pipeworx's 1419 structured data sources in one call. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the single-lookup alternative, 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?

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and breaking/current-news topics should go to ask_pipeworx. The depth parameter options are also tied to concrete use cases, so an agent knows exactly when to select this tool and how to calibrate 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 already establish read-only, idempotent, non-destructive behavior. The description adds valuable context: returns top-N relevant tools with full schemas and examples, and results are ready to call directly without a second lookup. This goes beyond the annotations by describing output format and the convenience of pre-populated schemas. No contradiction.

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

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

The description is two sentences, around 60 words, with front-loaded purpose and concise usage guidance. Every sentence adds value: what it does, when to use it, what it returns, and the 'call first' recommendation. 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?

Despite having no output schema, the description fully explains the return format: top-N tools with names, descriptions, and full input schemas, ready to call. It covers use cases, domain scope, and the meta-tool nature. Given the tool's moderate complexity, this description is complete.

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

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

Schema description coverage is 100% (all six parameters are described in the schema). The description does not add much beyond what the schema already provides, such as the 'limit' parameter meaning top-N. It slightly reinforces the purpose of 'query' as natural language, but the schema handles the heavy lifting, so the 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 uses a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings like search_datasets or deep_research by focusing on discovering tools rather than answering or searching data directly. It covers a broad domain list, making its scope explicit.

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

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

Explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when not to use it ('not just one answer'), implying more specialized tools are better for direct answers. This is strong guidance.

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

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

The annotations declare readOnly/openWorld/idempotent, and the description adds rich behavioral context far beyond that: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields (cik, recent_filings with URIs, latest 10-K fundamentals sorted by period_end DESC), describes a fallback chain (GDELT→GNews), and discloses the USPTO API sunset with soft-fail behavior. This gives the agent realistic expectations about data availability and 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 long but structured heavily with semicolons, parentheses, and a clear enumeration of return fields. It starts with relatable example queries, then the core function, then output details. Every sentence adds useful information; no filler or repetition. It earns a 4 because it's dense but maybe slightly longer than strictly necessary, though the complexity justifies it.

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

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

With no output schema, the description fully carries the burden of explaining return values. It lists all major output groups (cik + company_name, recent_filings with URIs and count, fundamentals with specific metrics and sorting, patents with sunset/soft-fail, news via fallback, LEI via GLEIF). It also states input constraints and gives a fallback for unsupported names, making the tool's behavior complete and predictable.

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

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

The schema already documents both parameters and covers 100% of them, so baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193'), emphasizing the zero-padded CIK requirement, and restating the no-names constraint with a pointer to resolve_entity. This reinforces parameter formatting and constraints 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 opens with concrete user intents ('Tell me about X', 'research Acme') and then states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for unsupported name inputs, distinguishing it clearly.

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

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

Provides explicit when-to-use guidance via example phrasings, an emphatic preference directive ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'), and a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' It also notes the patents API sunset and soft-fail behavior, further clarifying expected usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is disclosed. The description adds the specific context of deleting by key and the use-cases, but does not disclose additional behavioral traits beyond what annotations provide, like irreversible effects or required existence of the key.

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

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

The description is two sentences, front-loaded with the action, and every sentence carries useful meaning. It avoids redundancy and includes actionable guidance in a compact form.

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

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

Given a single parameter, no output schema, and annotations covering safety, the description sufficiently covers purpose and usage. It lacks details on return values or error behavior, but these are not critical for a simple deletion tool, making it almost 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 description coverage is 100% and the parameter 'key' is already described as 'Memory key to delete.' The description's 'by key' adds no new semantic detail beyond the schema, so the baseline 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 starts with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve), 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?

It provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names alternatives by saying 'Pair with remember and recall.' However, it lacks explicit when-not-to-use conditions, hence a 4 rather than 5.

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

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

Annotations provide readOnly, idempotent, and non-destructive hints, so the safety profile is already set. The description adds behavioral details like 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', giving a clear picture of the tool's workflow beyond the annotations. No contradiction.

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

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

The description is concise and front-loaded, with the main action stated in the first sentence. It includes only relevant details (what it does, output format, use cases) and avoids unnecessary fluff.

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 a single required parameter and no output schema, the description covers the key aspects: purpose, output format, and use cases. It does not discuss edge cases like inaccessible URLs, but given the tool's simplicity and good annotations, it is reasonably 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 already documents both parameters with 100% coverage, including default and max values for max_links. The description does not add additional meaning beyond what the schema provides, so it meets the baseline but doesn't exceed it.

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

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

The description uses a specific verb 'Generate' with a clear resource 'llms.txt file for any URL', and distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the file itself. It also specifies the output format and target audience.

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 provides explicit use cases starting with 'Useful for:' and names specific scenarios. It does not mention exclusions or alternatives, but the context is clear enough. No conflicting 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return payload details (fields, geometry type, record count, capabilities) but does not disclose additional behavioral traits such as authentication requirements or rate limits. With annotations present, the added context is useful but not extensive.

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, front-loaded sentence with no redundant words. It efficiently conveys the action, target, and outputs, making it easy to parse.

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

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

For a simple, read-only tool with one well-documented parameter and strong annotations, the description fully conveys what the tool returns and the type of resource it operates on. No output schema exists, so the explicit listing of return items is essential and provided.

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 provides 100% coverage for the single 'url' parameter, including its own description and an example. The tool description adds no further parameter-level 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 the specific verb 'Get' and clearly identifies the resource (ArcGIS Feature/Map Service layer schema) and the specific return contents: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer, which presumably retrieves actual data rather than schema.

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

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

The description implies usage for retrieving layer schema but does not explicitly state when to use this tool versus alternatives. No exclusions or references to sibling tools are provided, so the guidance is only implicit.

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

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

Annotations already cover read-only and safe nature; description adds the specific return fields and the scope of 'caller's' subscriptions, offering behavioral detail beyond annotations. No pagination or rate limit info, but acceptable for a simple list.

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

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

Three concise sentences: purpose, return fields, usage guidance. No wasted words, well structured.

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

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

Given the simple optional parameter and lack of output schema, the description lists the return fields and provides usage context. It's complete for this 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 covers include_inactive fully at 100% coverage. Description does not add parameter details, but the schema handles it, hitting the 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?

States clearly it lists the caller's active subscriptions with a specific resource and scope. Differentiated from sibling subscribe/unsubscribe tools by focusing on listing.

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

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

Explicitly states when to use it: before adding more subscriptions or to find an id to cancel. Provides clear context but does not name alternative tools explicitly or state exclusions.

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

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

Annotations are all false and provide no information, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), scope boundaries ('we cannot fix it... file it with that server instead'), and impact ('signal directly affects roadmap'). This goes well beyond what annotations offer.

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

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

The description is longer than ideal but every sentence contributes: purpose, use cases, scope exclusion, content guidance, rate limit, and quota. It front-loads the primary purpose and then progressively adds context. No filler or redundancy earns a 4.

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

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

Despite lacking an output schema, the description is remarkably complete for a feedback tool. It explains what to submit, what not to submit, how to identify the correct server, constraints (rate limit, quota), and what happens to the feedback (read daily, affects roadmap). It leaves no critical gaps for an agent deciding whether and how to invoke this 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds meaningful semantic guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This clarifies how to structure the message/context fields, which is not present in 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 opens with a specific verb+resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools (all research/query tools) by framing it as feedback submission. The follow-up sentence enumerates concrete use cases (bug, feature/data_gap, praise), leaving no ambiguity about intent.

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

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

Provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states a clear when-not-to-use: if the tool is from a different MCP server, file it there instead. This is exemplary alternative/scope 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 establish read-only, idempotent, open-world behavior. The description adds meaningful context: it is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes beyond the annotations but doesn't fully describe edge cases like empty results or rate limits.

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

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

The description is front-loaded with the core result, followed by three numbered use cases and a brief note on data source/privacy. It is a bit longer than strictly necessary, but each sentence adds value and the structure is 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?

For a simple read-only stats tool with one optional parameter and strong annotations, the description covers the essential return content (top tools, top packs, call volume), caching behavior, and privacy characteristics. It lacks an explicit output schema but provides enough for an agent to understand expected results.

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 'window' parameter is fully documented in the schema with enum values and meaning. The tool description merely echoes the schema's note about shorter vs. longer windows without adding novel semantic insight, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: it 'Returns the top tools, top packs, and total call volume' from Pipeworx. It also lists concrete use cases, distinguishing it from siblings like ask_pipeworx or discover_tools by focusing on aggregate popularity 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?

Explicit use cases are provided (e.g., discovering hot data sources, confirming canonical tools, aligning with agent needs). However, it does not mention when not to use or explicitly name alternative tools, so it falls short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses critical behavioral details: the 3pp partition deviation threshold, the placeholder-slug filtering and >20% placeholder fraction null behavior, the Jaccard similarity anchor (≥0.30), and the fill-check logic that uses live CLOB depth to determine whether an edge is realizable. It also explicitly warns against executing trades on non-realizable edges.

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

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

The description is dense but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every section contributes actionable guidance—no filler or tautology. The length is justified by the tool's complexity and the absence of an output schema, which makes the response description necessary.

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

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

Given the tool has two optional parameters, no output schema, and a complex multi-mode behavior, the description is exceptionally complete. It describes the response shape (opportunities[], partition_check fields), the fill check pricing, failure conditions (realizable_edge_pp <= 0), and points to polymarket_fill_risk for custom sizing. Nothing essential is missing.

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

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

Although the schema already describes the event and topic parameters at 100% coverage, the description adds substantial meaning: it gives concrete slug examples, explains the mechanics each parameter triggers ('walks child markets', 'searches related events across the platform'), clarifies that no arguments performs a trending scan, and introduces semantic/partition filtering behavior. This goes well beyond the schema's basic 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three operational modes (trending_scan, event, topic) and differentiates itself from sibling tools like polymarket_edges or polymarket_fill_risk by the unique arbitrage detection mechanism.

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 instructions are given for when to use which mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides an alternative for sizing: 'For custom sizing use polymarket_fill_risk', and warns when not to trade ('do not trade it' when realizable_edge_pp <= 0).

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

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

The description goes far beyond the annotations. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), explains the internal model families and response segments, details the edge fields (edge_pp_net, kelly_fraction, etc.), and warns about the 24h-move signal. It also explains the purpose of diagnostics and why Fed bets are excluded. This is rich behavioral context that the annotations (readOnlyHint, idempotentHint) do not cover.

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 densely packed with relevant information. It uses clear structure (uppercase section headers, numbered model families, explicit knob lists) to organize the content. Every sentence contributes value, although the sheer volume of detail might overwhelm some agents. It is appropriately sized for a complex tool with 9 parameters and rich output.

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

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

Despite having no output schema, the description thoroughly defines the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and explains the data fields within opportunities. It covers the main user-facing behaviors, edge-case handling (e.g., placeholder-slug filter, partition >20% placeholder skip), and even the reasoning behind excluding Fed bets. This is as complete as a text description can be for a complex tool.

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

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

The schema already provides 100% parameter coverage, giving a baseline of 3. The description adds meaningful context for several knobs: it explicitly explains min_liquidity / max_spread_pp as 'tradeable-edge filters' and min_partition_leg_kelly as a per-leg filter with rationale. It also clarifies slippage_pp's effect on edge_pp_net. Not every parameter is re-explained, but the added semantics elevate the score above baseline.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the tool's purpose and adds a distinctive use case ('what should I bet on today'), which sets it apart from generic market search tools. The detailed segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT further clarifies the scope.

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

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

The description clearly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This provides clear context for when to use the tool. However, it does not explicitly mention alternative sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) or give exclusion criteria, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds significant behavioral detail: data gaps explained via 'snapshots are written when polymarket_edges runs on a cache-miss', history depth limited by '60-day snapshot TTL', and decay computed 'from daily closes of edge_pp_net (net of default slippage), not intraday'. This exceeds the value of annotations and fully discloses limitations.

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

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

Though the description is relatively long, it is highly structured with clear sections for purpose, arguments, response, and limits. Every sentence provides necessary information, especially given the absence of an output schema. It is front-loaded with the core purpose and avoids fluff.

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?

Without an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), including field meanings and lifecycle semantics (e.g., 'GONE from the latest'). It also covers critical limitations (TTL, snapshot gaps) and the source of decay numbers, making the tool's behavior and output sufficiently clear for an agent to invoke and interpret 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?

The schema already provides descriptions for both parameters with 100% coverage, so the baseline is 3. The description adds semantic nuance by defining 'window' as a 'snapshot family' and clarifying the role of 'days' as a lookback with a max of 30. This enriches understanding beyond the schema's simple defaults and enums.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers the question 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools by focusing on historical edge analysis rather than raw edge data or other 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 context about when the tool is relevant (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and implies that it is used for analyzing edge persistence/decay. However, it does not explicitly state 'use this when...' or name alternatives, such as polymarket_edges for current edges. Usage is implied rather than explicitly guided.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses rich behavioral details: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and highlights risks such as partial basket fills converting an arb into an unhedged directional position. It also explains how size_usd is interpreted differently for buys vs sells and in basket mode, giving the agent a clear expectation of side effects and edge cases.

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

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

The description is long but every sentence contributes critical information for a complex tool with two operating modes. It is front-loaded with the core purpose, then structured by mode (SINGLE-MARKET, BASKET) and usage guidance. Each return field and behavioral nuance is mentioned once, with no repetition or filler. The length is appropriate for the tool's complexity.

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

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

Given the tool's complexity (4 parameters, two modes, no output schema, and nuanced risk semantics), the description is remarkably complete. It lists all expected return values (e.g., vwap_fill_price, max_fillable_usd, thin_legs[], forced_directional_risk) and explains the verdict categories. It also integrates with sibling tools by naming when to use it, making it fully contextual for an AI 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?

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies that `market` and `event` are mutually exclusive modes, interprets `side` for each mode (including auto-detection for basket), and explains that `size_usd` means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. This is far more than the schema's basic field descriptions, fully compensating for any gaps.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This names the exact action (check edge realizability), the resource (CLOB order book), and immediately distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk. The two modes (single-market and basket) are explicitly laid out, leaving no ambiguity about the tool's purpose.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and how to choose between single-market and basket modes. This clearly positions the tool relative to its siblings and gives concrete criteria for when to invoke 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 read-only, open-world, idempotent, and non-destructive. The description goes well beyond by explaining compatibility_warning conditions (matched_pairs:0 analysis), temporal_alignment semantics, and skipped_cross_type/subtype counters. It even warns about the tool returning warnings for most pre-mapped topics, which is a valuable behavioral disclosure.

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

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

The description is dense and detailed, but every sentence adds information, from modes to response fields to safety warnings. It's front-loaded with the core purpose and structured clearly. While lengthy, the complexity of the tool justifies the length; only minor redundancy (e.g., repeated emphasis on the same warning) prevents a 5.

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

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

Despite lacking an output schema, the description covers the response shape (leg-by-leg prices, spread[].top_spreads_pp), safety fields, temporal alignment, and skip counters. It thoroughly explains edge cases and limitations, leaving little ambiguity for an agent selecting or invoking the tool.

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

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

Schema coverage is 100%, with each parameter having a description. The tool description adds context about the two modes and override behavior, but this mostly mirrors the schema descriptions. Baseline 3 is appropriate because the description adds marginal 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 function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb phrase and distinguishes from siblings by explicitly naming both venues, while tools like polymarket_arbitrage likely focus on a single venue or different comparison.

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

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

The description provides clear usage context: two modes ('topic' and explicit ticker/slug) and details about when results are meaningful vs. when compatibility warnings indicate non-tradeable spreads. It doesn't explicitly name alternative tools but effectively communicates the tool's niche. The caveat 'pre-mapped ≠ tradeable' offers guidance on interpreting results.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that it returns attribute rows and geometry, which is useful behavioral context beyond the annotations. There is no contradiction between the description and the annotations.

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

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

The description is two sentences: the first states the purpose and lists the parameters, and the second gives a useful tip. It is front-loaded, concise, and contains no filler or redundancy. 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?

Given the tool's moderate complexity (6 params, 1 required) and rich annotations, the description covers the essentials: what it does, the source of the URL, and return type. Without an output schema, it could specify the output format in more detail, but it is still complete enough for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage of the 6 parameters with descriptions, so the baseline is 3. The description adds a cohesive usage pattern (e.g., the sampling example) that ties the parameters together, and it lists the key parameters in the first sentence. This goes slightly beyond the schema alone, earning a 4.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer via URL, with the specific verb 'Query' and a clear resource. It distinguishes from siblings like layer_info by specifying it returns attribute rows and geometry, and it connects to search_datasets as the source for URLs.

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

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

It explicitly mentions the URL comes from search_datasets, providing a clear workflow context. It also gives a practical sampling tip (where='1=1' + out_fields='*') that guides when to use it for exploration. However, it does not explicitly exclude alternatives or state when not to use it, so it is slightly below a perfect score.

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

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

The description adds valuable behavioral context beyond the annotations, including scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the mode-switch behavior (omitting the key argument lists all saved keys). This goes beyond the readOnly/idempotent hints and helps the agent understand privacy and output variations.

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 long, front-loaded with the primary action, and every sentence adds value. It covers functionality, use cases, and scoping without any redundancy or fluff.

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 1-parameter tool with no output schema, the description is sufficiently complete. It covers what the tool does, when to use it, its scoping rules, and its relationship to remember/forget. No additional context is necessary 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?

The input schema already provides 100% coverage of the single key parameter with the note 'omit to list all keys', and the description essentially repeats this semantics. Per the rubric, when schema coverage is high, a baseline of 3 is appropriate; the description does not add significant new parameter information.

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 with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly distinguishes it from siblings by describing its dual behavior (get a value or list all keys). The mention of 'remember' and 'forget' as companion tools further clarifies its role.

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

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

The description provides clear when-to-use guidance with concrete examples ('the user's target ticker, an address, prior research notes') and explains the benefit ('without re-deriving it from scratch'). It does not explicitly name alternative tools or state when not to use it, but the context is sufficiently clear.

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

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

The description discloses that setting mark_read:true flags returned events as read and affects subsequent calls, which implies a state change. This directly contradicts the annotation readOnlyHint=true and also challenges idempotentHint=true, as repeated calls may return different results after marking events read. This is a clear annotation contradiction, so the score is 1.

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

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

The description is a single, well-structured paragraph of four sentences, each serving a distinct purpose: what the tool does, what it returns, how to filter, and a note on polling/alternate access. It is concise, front-loaded with the main verb, and contains no filler, though it could be slightly more organized with bullet points for the details.

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

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

Given the tool has no output schema and 5 parameters, the description covers key contextual points: return fields (source, citation_uri, raw payload), filtering options, mark_read behavior, and an alternative access URL. It does not explicitly describe unread_only, but the schema covers that. The description is sufficiently complete for an agent to understand the tool's role and data flow.

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 all 5 parameters with descriptions, so the baseline is 3. The description adds meaningful semantics beyond the schema: it provides a concrete example for type ('sec_8k'), clarifies that since is an ISO timestamp, and explains the behavioral consequence of mark_read ('the next call only shows newer ones'). This added value justifies a score of 4.

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

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

The description clearly states the tool's specific function with verb+resource: 'Pull fired events from your subscription feed.' It goes beyond a generic statement by describing the returned data (source, citation_uri, raw event payload) and distinguishing itself from sibling tools like list_subscriptions and subscribe/unsubscribe, which focus on subscription management.

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 practical usage context: 'Polls work fine' indicates this is suitable for polling workflows, and it mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It does not explicitly exclude or compare to sibling tools, but the context is clear enough for selecting this tool for reading subscription alerts.

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) are consistent; description adds context about multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, API sunset soft-fail, and returns citations. This goes beyond annotations to disclose failure modes.

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

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

Dense but well-packed; front-loaded with natural-language triggers, then sources, then input formats, then output and alternative. No wasted sentences, though a single long paragraph could benefit from structural breakers; still highly scannable.

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

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

No output schema, so description explains return shape ('structured changes[] grouped by source + total_changes count + citation URIs'). Also covers multi-source behavior and fallback. Could mention pagination or empty-result behavior, but for complexity this is strong.

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

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

Schema already describes all 3 parameters with examples and typical values ('Use 30d or 1m'). Description repeats this, adding only the conceptual context of the window and entity but no new syntax beyond schema. Since coverage is 100%, baseline 3.

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

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

Description clearly states it's a change feed for a company over a time window, explicitly listing sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing from entity_profile. The verb 'fans out' and action of returning structured changes make the tool's 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?

Provides explicit query examples ('What's new with X', 'latest on Y'), describes when to use, and directly says 'Use entity_profile instead when you want the static profile' — a clear alternative. Also notes fallback behavior and limitations (USPTO soft-fail), guiding when to expect results.

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 and non-destructive write, but the description adds scoping ('scoped by your identifier') and retention policies (persistent for authenticated, 24 hours for anonymous). This is substantive behavioral context beyond the annotation flags.

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 deliver a clear purpose, usage guidance, storage model, persistence behavior, and sibling pairings. Every sentence contributes unique information, and the description is front-loaded with the verb.

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

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

For a two-parameter write operation with no output schema, the description covers what to store, when to use it, how persistence works, and related tools. The absence of return-value details is acceptable. This is complete for its 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 covers both parameters with clear descriptions and examples. The description adds only the phrase 'key-value pair' which mirrors the schema, providing no additional semantic detail. With 100% schema coverage, 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 opens with a specific verb ('Save') and resource ('data... to reuse later'), and distinguishes this from siblings by mentioning recall and forget as complementary operations. It also specifies the key-value storage model, making the tool's 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?

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples. It also pairs with recall and forget, giving clear context for when to use this vs alternatives. The persistence details (authenticated vs anonymous) guide usage expectations.

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

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

The description enriches the annotation data by explaining that each call cascades through several lookup endpoints, auto-disambiguates input, and returns specific citation URIs. It adds behavioral insight beyond the readOnly/idempotent hints, 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 information-dense but well-organized with supported types clearly labeled. The initial examples are slightly noisy but effectively front-load the core purpose. Every sentence contributes, though a few could be trimmed for snappier delivery.

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?

Without an output schema, the description fully covers return values (ticker, CIK, RxCUI, etc.) and even explains the internal cascading behavior. It is complete for the tool's complexity, covering both entity types and their output formats.

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 covers both parameters with complete descriptions, but the tool description adds valuable practical detail: examples (AAPL, CIK, 'ozempic'), input formats, and accepted variants. This goes beyond the baseline 3 for full schema coverage.

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

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

The description clearly states the tool resolves a user-spoken name to the canonical identifier needed by other tools, with specific examples and supported types (company, drug). It distinguishes itself from siblings like entity_profile or compare_entities by focusing on identifier lookup rather than profile or 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use directive. It doesn't name specific alternatives or say when-not, but the context is clear and it even notes it replaces 2-3 manual lookups.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description only needs to add context. It discloses that the tool calls ai_visibility_check per entity, ranks by score, and returns a ranked list with score, confidence, and signal density—valuable behavioral detail beyond the annotations.

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

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

The description is two sentences long, front-loads the action, and avoids redundancy. Every clause adds information, from the probing mechanism to the output format.

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

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

For a tool with no output schema, the description explains the return value (ranked list with score, confidence, signal density) well. It also gives a clear use case and mentions the underlying ai_visibility_check dependency, making the tool's function and context sufficiently clear.

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

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

The input schema has 100% parameter description coverage, so the description adds little extra meaning for parameters. It does mention entities as 'your brand + N competitors' and 'first entry treated as subject', which partially reinforces the schema, but does not add new 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 compares AI visibility across multiple entities side-by-side, with a specific verb and resource. It differentiates from sibling tools like ai_visibility_check (which likely checks a single entity) by emphasizing multiple entities and ranking.

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

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

The description includes a concrete use case—competitive AI-marketing audits—with an example question. However, it does not explicitly state when not to use this tool or name alternatives, though the context implies ai_visibility_check for single entities.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: composite fan-out across two services, graceful partial-failure degradation, the 5-30s latency for first bundlephobia measurement, and the sources_failed field. This adds valuable context beyond what annotations provide.

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

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

The description is dense but every sentence adds value. It is front-loaded with the core purpose, then lists return fields, scope limitations, and failure behavior. The use of em-dashes and semicolons keeps it readable without redundancy.

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

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

With no output schema, the description thoroughly explains return values (summary block, advisories, links, recent versions), covers ecosystem limitations, and addresses failure modes. For a multi-source composite tool, this level of detail is complete and well-suited for agent decision-making.

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

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

Schema coverage is 100% and both parameters are already described in the schema (package name, optional version). The description does not add new parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific purpose: a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It explicitly differentiates this tool from siblings by naming the data sources and the exact question it answers, making it easy to select.

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

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

Provides explicit when-to-use guidance for common agent questions ('is X safe / popular / small' or 'what does adding lodash cost me'). It also gives an explicit alternative: non-npm ecosystems like PyPI/Maven/Cargo/Go should fall under deps.dev:version directly, preventing mis-selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful context by specifying the return fields (name, summary, record_count, owner/org, url) and chaining to query_layer/layer_info. It does not contradict annotations. No extra behavioral traits like rate limits are mentioned, but the safety profile is covered.

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

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

The description is two sentences that are clear and front-loaded. The first sentence states the action and scope; the second details outputs and integration. No unnecessary information, every word earns its place.

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

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

For a simple tool with 3 optional parameters, no required parameters, and no output schema, the description fully explains what it does, what it returns, and how the output connects to other tools. The absence of an output schema is compensated by listing the specific return fields. Complete for its 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 description coverage is 100%, with each parameter (query, limit, org_id) already well-documented. The description adds no additional parameter-specific meaning beyond referring to 'keyword' search, which aligns with the query parameter. Baseline 3 per rubric 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 uses a specific verb ('Search') and identifies the exact resource ('Washington DC GIS open geospatial datasets') with examples (parcels, zoning, etc.). It also distinguishes from sibling tools by stating the output URL is meant for query_layer / layer_info, making the tool's role in a pipeline clear.

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

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

The description implies when to use this tool (to find datasets by keyword) and provides guidance for downstream usage ('pass that url to query_layer / layer_info'). However, it does not explicitly state when not to use it or name alternatives for dataset discovery, so it misses the full 'when-not' clarity.

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

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

Annotations already mark it read-only and idempotent, but the description adds critical behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, and truncation flag. It also discloses that offsets enable verbatim quote verification, which is useful for the agent.

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

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

The description is front-loaded with the main verb and resource, then adds use-case, pairing, and technical detail in a logical order. Every sentence contributes new information—no filler or repetition of the schema.

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

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

The description covers the return format (passages, offsets, scores), the truncation behavior, the pairing with a sibling tool, and the algorithmic details. Without an output schema, this is sufficient for an agent to understand what to expect from the tool and when to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond property names: it clarifies that 'text' must be a previously fetched record, gives query examples, and explicitly ties the char cap to the 'text' parameter. This extra context helps the agent construct correct calls.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb+resource that clearly distinguishes it from siblings like ask_pipeworx_grounded. It also states the return values (top-N passages with offsets and similarity scores), making the tool's purpose unambiguous.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, explaining the workflow: fetch with the gateway, then ground over relevant passages. This gives clear when-to-use context and an alternative for broader grounding.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds important behavioral traits: requiring a Pipeworx OAuth account (anonymous + BYO cannot persist), the always-on feed with retrieval methods, SMS phone verification with a 10/day cap, and the return of a new subscription id. These details help the agent understand side effects and constraints beyond the basic mutability flag.

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

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

The description is front-loaded with the core purpose ('Create a proactive monitoring subscription'), then efficiently packs requirements, types, and delivery channels into a few dense sentences. It avoids fluff and every sentence carries information. A more structured bullet format could improve scannability, but the text is reasonably concise for the complexity.

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

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

Given the tool's moderate-high complexity (3 parameters, nested objects, multiple subscription types, no output schema), the description covers essential aspects: purpose, return value, auth requirement, supported types with examples, delivery channels, and specific constraints. It omits the webhook delivery channel (though the schema describes it in detail) and does not explain the return object beyond the id, but the rich schema compensates. Overall, it is nearly complete but with a few 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?

The schema has 100% description coverage, so the baseline is 3. The main description largely restates the schema's parameter details but adds a useful semantic example ('items:["5.02"] = officer change') that clarifies the meaning of a specific value. Overall, the description contributes marginal extra meaning beyond the schema, so a 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 specific action: 'Create a proactive monitoring subscription to a live-data event stream.' It names the return value (new subscription id) and lists supported types, making the tool's purpose unmistakable and 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 clear context for when to use the tool: to set up proactive monitoring. It also notes prerequisites (OAuth account) and explains that the feed channel is always on and can be pulled via recent_alerts or a direct endpoint, implying these are alternatives for reading data rather than subscribing. However, it does not explicitly mention sibling tools or when not to use it, so it lacks explicit exclusions.

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

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

Annotations already disclose read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds useful context about the return format (category-bucketed example questions drawn from the live catalog) and the onboarding purpose, going beyond what annotations convey.

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

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

The description is relatively long but well-structured, front-loaded with natural-language example queries, then explaining purpose, return value, and usage. Each sentence contributes context; while it could be trimmed, the onboarding nature justifies the detail.

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

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

Given the simple parameter schema, strong annotations, and no output schema, the description is complete enough. It explains what the tool returns, how to call it with or without arguments, and when to use it. No critical gaps for an agent to select and invoke it correctly.

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

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

The schema already provides 100% coverage for the single optional `topic` parameter, including its meaning and examples. The description essentially repeats the same information ('pass topic to focus', examples like 'finance', 'pharma'), adding no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool + argument shape. It distinguishes itself from siblings by explicitly telling the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and names the meta-tools it teaches.

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

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

The description provides clear when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do') and mentions alternatives (ask_pipeworx, entity_profile, compare_entities) to learn about. However, it does not explicitly state when NOT to use it, making this a strong 4 but not a 5.

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

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

The description adds important behavioral details beyond annotations: ownership enforcement ensures only the user's own subscriptions can be canceled, and the row is deactivated rather than deleted, preserving historical events. This complements the idempotentHint and destructiveHint=false annotations, providing concrete context about the mutation's impact.

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

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

The description is two concise sentences with a clear action-first structure. Every sentence provides meaningful information without redundancy, making it easy for the agent to parse.

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

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

For a single-parameter tool with no output schema, the description covers the main behavior, ownership rules, and the side effect on historical data. It lacks explicit error handling details, but the given context is sufficient for a simple cancel operation.

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

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

The schema already fully describes the 'id' parameter as the subscription id returned by subscribe, with 100% coverage. The description does not add further parameter-specific details, so it remains at the baseline for high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription') and the object ('by id'), which differentiates it from sibling tools like 'subscribe' and 'list_subscriptions'. It also specifies the ownership constraint and the soft-deactivation behavior, adding further clarity.

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 context that this tool cancels subscriptions and enforces ownership, implying it is the appropriate tool for unsubscribing from alerts. However, it does not explicitly mention alternatives or when not to use it, such as a hard-delete scenario. The reference to recent_alerts clarifies the side effect, but no explicit when/when-not guidance is provided.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive hints, the description discloses the two-path processing algorithm (SEC EDGAR fast path vs. grounded pipeline), the exact percent-delta math for financial claims, and the return structure (verdict, actual value with citation, reasoning). It does not detail potential latency or failure modes, but adds meaningful behavioral context.

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

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

The description is well-structured and efficient: it opens with example triggers, explains the core function, gives routing specifics, and outlines outputs—all in a few dense sentences. No wasted words; every sentence contributes to clarity.

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

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

Given the tool's complexity and lack of an output schema, the description fully explains the return values (verdict types, citation, reasoning) and the behavior for both financial and non-financial claims. It covers the full scope of operation, including fallback behavior, without requiring a separate 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% for both claim and tolerance_pct, which would be a baseline 3. The description adds extra guidance for tolerance_pct, specifically recommending 1–2 for hallucination detection and explaining default is implied by wording capped at 5, enriching the semantic meaning beyond the schema.

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

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

The description clearly identifies the tool as a claim verification function, with specific verbs like 'validate', 'verify', and 'fact check' and a defined resource (natural-language factual claims). It includes example phrasings to disambiguate from general question-answering siblings like ask_pipeworx and distinguishes itself by focusing on truth assessment against authoritative sources.

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

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

Explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It further provides routing guidance for company-financial claims vs. other claims, and mentions replacing 4–6 sequential calls, giving clear context for choosing this tool over alternatives.

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