Arcgis Johnsoncity

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

Annotations already indicate readOnly and idempotent behavior, and the description adds valuable context: it explains that the tool makes external LLM calls, that Anthropic calls require a user-provided API key, and that the user pays Anthropic directly. It also discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is beyond the annotation hints. It does not mention rate limits or potential non-determinism, but the confidence field partially covers uncertainty.

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 short sentences, each covering a distinct aspect: purpose, configuration/cost, return format, and use cases. There is zero filler or redundancy. It is front-loaded with the core purpose, making it easy to scan, and 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?

With no output schema, the description takes responsibility for explaining what the tool returns, and it does so clearly: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also covers model selection, cost implications, and typical use cases. Given the moderate complexity (4 params, 1 required), this is a complete description that leaves no major questions unanswered.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter context by stating the default model (Workers AI Llama-3.3-70b, free) and explaining that _apiKey is only needed for Anthropic and is passed straight through. It also clarifies the `context` parameter's disambiguation purpose implicitly through the examples. This goes beyond the schema descriptions, making the tool easier to invoke correctly.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility.' It clearly states the output (0-100 visibility score) and the scope (per model), distinguishing it from sibling tools like ask_pipeworx or deep_research. The use cases (AI-marketing audits, pre-launch brand checks) further clarify its niche.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains how to choose between models (default Workers AI vs. Anthropic with _apiKey), which acts as practical usage guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it does not earn 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds valuable behavioral context: the tool routes across 5,724 tools/1497 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is a single fast call. It stops short of describing failure modes or response structure in detail, but the annotations lower the burden.

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

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

The description is lengthy but every section earns its place: scope, routing behavior, trigger phrases, examples, and escalation path to siblings. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured so an agent can parse it quickly. Slightly verbose but not wasteful.

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 single-required-parameter tool with no output schema, the description covers all decision-relevant context: what it does, when to use it, when not to, examples, alternatives, and expected output (structured answer with citations). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% with all six parameters documented, so the baseline is 3. The description adds practical semantics by framing the primary 'question' param with natural-language examples (unemployment rate, 10-K, adverse events, patents, forecast, clinical trials), showing the expected style of input. This goes beyond just naming the parameter.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and immediately enumerates concrete domains (SEC filings, FDA data, FRED/BLS, USPTO patents, etc.), making the verb-resource relationship explicit. It clearly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different use cases. This leaves no ambiguity about what the tool does.

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

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

The description gives explicit invocation triggers: the phrases 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', and any factual question. It states 'START HERE for most questions' and gives precise step-up conditions for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). This is textbook usage guidance.

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

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

Beyond the annotations, it reveals that candidate routing improvements are enabled live only when under test, that none is currently active, and that behavior currently matches ask_pipeworx exactly. It also clarifies this is a fully working router, not a stub, which is valuable behavioral context the annotations cannot 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 dense but not bloated; every sentence contributes meaningful context about the beta status, current active state, and usage. It is slightly long because it packs a lot of detail, but the information is all relevant and correctly front-loaded.

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

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

For a tool with a simple one-parameter schema, rich annotations, and no output schema, this description is nearly complete. It covers what the tool is, its relationship to the stable router, when to use it, current behavior, and expected response consistency. It only lacks explicit guidance on choosing between the beta and grounded variants.

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 documentation covers all parameters at 100%, including a clear description for the required 'question' field and its aliases. The description adds no param-specific semantics, but the schema already carries that burden, so the baseline 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 is explicit: this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling by labeling the experimental version and explaining the routing-improvement 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?

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It could more directly state when to choose ask_pipeworx or ask_pipeworx_grounded instead, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: refusal reasons, the constraint of using only tool result content, the explicit refusal shape, and the extra LLM call cost. No annotation contradiction exists.

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 every sentence earns its place: it front-loads the core mode, explains routing and extraction behavior, gives the full return/refusal shape, provides use cases, and states the cost tradeoff. The length is justified by the absence of an output schema and the tool's high-stakes context.

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

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

For a complex tool with no output schema, the description is remarkably complete: it specifies the success return fields, all refusal reasons, the extraction constraint, when to use it, when not to, and the cost difference versus the sibling. An agent has everything needed to invoke it correctly and interpret its result.

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 all six parameters clearly documented as aliases for the natural-language question. The description adds no parameter-level detail beyond what the schema already provides, 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?

States a specific verb and resource: a grounded, hallucination-resistant answer mode that extracts answers only from fetched tool results. It distinguishes itself from ask_pipeworx by name, clarifies the shared routing, and gives a concrete return shape. An agent can tell exactly what this tool does and how it differs from its 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?

Provides explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with examples of high-stakes domains. It also names the alternative (ask_pipeworx) and states when to prefer it, including the cost tradeoff of one extra LLM call.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond with operational details: resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits (status:'low_confidence_match' for low-confidence matches, status:'market_closed_or_inactive' for dead markets), wide-spread illiquidity warnings, and cancellation-rule risk (refund_50_50 with EV impact). This is exceptional 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 long but exceptionally well-structured with clear section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds operational value. It is not 'concise' in length but is efficiently organized and front-loaded with the core purpose. A 5 would require tighter prose; a 4 reflects good structure despite length.

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 (classifiers, many data sources, resolver logic, response shapes, safety behavior) and the absence of an output schema, the description is remarkably complete. It covers response shapes (result.market, result.analysis, result.evidence, result.parent_event), news fields, blocking behaviors, and cancellation rules. No critical context is missing.

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

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

Schema description coverage is 100%—all three params (market, depth, include_raw) have detailed descriptions. The tool description adds real-world input examples (slug, URL, question text) and explains how the resolver handles ambiguous matches, which nuances the market parameter. Given the high schema coverage, a baseline of 3 applies, but the description's examples and resolver context push it to 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 opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states what the tool does (resolves, classifies, fans out, returns evidence packet + market-vs-model comparison) and distinguishes it from general research tools like ask_pipeworx and edge-specific tools like polymarket_edges.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples across bet categories. However, it does not explicitly state when NOT to use the tool or mention alternative sibling 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?

Even with annotations (readOnlyHint, openWorldHint, idempotentHint) already covering safety, the description adds substantial behavioral context: it pulls specific financial metrics from SEC EDGAR/XBRL for companies and FAERS/FDA/trial data for drugs, handles off-calendar fiscal years correctly, sorts by primary metric so 'largest' reads off the top, and returns paired data with citation URIs. This far exceeds the structured 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 longer than average, but every segment earns its place: trigger phrases, explicit preference rule, per-type data details, sorting behavior, and return format are all packed in. It is front-loaded with the most important usage cues and uses formatting (quotes, em-dashes) for readability. It could be slightly tightened, but the density of useful information justifies the length.

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 only 2 params, no output schema, and clear annotations, the description fully explains what the tool does, how it behaves, what data it returns (paired data + citation URIs), and why it should be preferred. It even anticipates edge cases like off-calendar fiscal years. For a tool of this complexity, the description is remarkably 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 covers both parameters with descriptions (100% coverage), so a baseline of 3 is warranted. However, the description adds significant semantic value by explaining what each type actually retrieves (e.g., 'company' → latest 10-K revenue + net income + cash + long-term debt; 'drug' → FAERS counts + FDA approvals + trial counts), and by giving concrete examples for values (tickers/CIKs vs drug names). This goes beyond the schema's minimal definitions.

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

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

The description opens with concrete query examples ('Compare X and Y', 'X vs Y', 'rank these companies') and states the core function: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes itself from sequential lookups ('Replaces 8–15 sequential lookups') and from sibling tools like entity_profile by explicitly focusing on multi-entity 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving direct usage guidance. It also lists example queries that should trigger this tool, implicitly covering when to use it. No exclusion criteria are needed because the examples plus the 'ALWAYS PREFER' instruction clearly delimit the intended use case.

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 signal readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: parallel tool routing, findings packet composition, gaps[] for unanswered facets, contradictions[] scanning, citation fetchability guarantees, excerpting behavior, and expected latency of 15-60s up to ~90s. It even discloses account and paid-plan requirements.

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 information-dense and front-loaded with the account requirement and the sibling alternative. Some depth behavior is repeated between the schema and the prose, and the many clauses make it dense, but every section delivers actionable information for a complex tool.

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

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

With no output schema, the description fully documents the return shape: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, hop fields, gaps[], and contradictions[]. It also covers auth, latency, source scope, and when to prefer ask_pipeworx, leaving no critical decision or invocation detail unaddressed.

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. The description goes beyond the schema by linking depth:'thorough' to a paid plan, explaining that standard recovers gaps and thorough chases leads, and clarifying that the question can be broad and multi-part. This adds practical meaning beyond the enum 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 names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' with decomposition and parallel routing to 5,724 tools. It also explicitly contrasts itself with open-web search and distinguishes itself from ask_pipeworx and news-focused siblings.

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 and when-not-to-use guidance: 'best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. These exclusions name the exact alternative tool and the conditions that select it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral context beyond annotations: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and results are 'ready to call directly, no second schema lookup needed.' This describes return behavior meaningfully.

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

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

Four sentences with a clear front-loaded purpose ('Find tools by describing the data or task'). The long domain list is arguably verbose but informative, and every sentence contributes to understanding when and how to use the tool. No redundant 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?

For a tool with no output schema, the description clearly states what is returned (top-N tools with names, descriptions, schemas) and the intended use case. It addresses the core needs of an agent: what it does, when to use it, and what to expect. Minor omissions like relevance ordering or edge cases don't detract significantly.

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 all parameters with descriptions and aliases, giving high coverage. The description adds a wide list of example topic areas (SEC filings, FDA drugs, etc.) that help formulate queries, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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: 'Find tools by describing the data or task.' It distinguishes itself from siblings by being a meta-tool discovery service, explicitly listing the types of data/tasks it covers and noting it returns full schemas, making it unique among search-oriented siblings.

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 usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and a strong directive 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use it (when you have one specific answer in mind), though it doesn't name alternative tools explicitly.

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, idempotent, non-destructive behavior, but the description adds substantial context: it fans out across five sources, notes the patent API sunset with a soft-fail, mentions the GDELT→GNews fallback chain, and details the return structure (e.g., 'fundamentals (LATEST 10-K... sorted period_end DESC)'). This goes beyond the annotations and sets accurate expectations about limitations.

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

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

The description is long but information-dense: every sentence earns its place. It opens with concrete user prompts, immediately states the core purpose, then packs in sources, return fields, and input constraints using a compact semicolon-separated structure. There is no fluff or 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 fully covers the return contract: CIK and company name, up to 5 filings with URIs, specific fundamentals metrics and sorting, patent status and soft-fail, news fallback chain, and LEI. It also covers input formats and the resolve_entity alternative. This is highly complete for a complex cross-source tool.

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

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

Schema description coverage is 100%: the schema already explains the 'type' enum and 'value' as ticker/CIK with the 'names not supported' caveat. The tool description repeats this information nearly verbatim, without adding new meaning beyond the schema. The baseline of 3 applies because the description does not enrich parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's function with a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It is distinguished from siblings through the explicit 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' guidance and by listing the exact data sources and return fields, leaving no ambiguity about what the tool does.

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

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

The description includes explicit usage timing ('when the user asks for a holistic view'), a strong preference directive ('ALWAYS PREFER'), and clear when-not-to-use guidance: names are not supported, so 'use resolve_entity first if you only have a name.' This provides clear alternatives and 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 indicate destructive and idempotent behavior, so the bar is lower. The description adds useful context about the scope (previously stored memory, sensitive data) and relationships with siblings, without contradicting 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?

Two concise sentences, front-loaded with the primary action, followed by usage guidance and sibling reference. No unnecessary words or repetition of schema 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?

For a simple deletion tool with one parameter and no output schema, the description covers the purpose, usage conditions, and relationship to siblings. It doesn't detail error handling for missing keys, but the idempotent annotation partially addresses that, and such detail is not essential for a basic delete.

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 describes the single 'key' parameter with 'Memory key to delete' at 100% coverage. The description's phrase 'by key' doesn't add meaningful semantics beyond the schema, 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 opens with a specific action and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like 'remember' and 'recall' by specifying the delete operation on memory entries.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' providing clear context relative to alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits a 'single text blob ready to drop at site-root/llms.txt.' This goes beyond the annotations by explaining the internal pipeline and output format, though it does not discuss error handling or network failures.

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-loaded with the core purpose, and every clause adds value. It efficiently covers what the tool does, how it does it, the output format, and concrete use cases without any fluff or repetition.

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

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

For a simple two-parameter tool with no output schema, the description sufficiently explains the output format and use context. It covers the main workflow and expected deliverables. It lacks mention of potential failure modes (e.g., unreachable URLs) or prerequisites, but given the tool's simplicity and the strong 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?

Schema description coverage is 100%, and both parameters (url, max_links) are already well-described in the schema, including default and max values for max_links. The description adds minimal semantic value for parameters, only reinforcing that the URL can be any site or landing page. This meets 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 specific action: 'Generate a production-ready llms.txt file for any URL' and follows with the concrete steps of fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. It distinguishes this tool from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than merely checking visibility or scanning 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?

The description gives explicit use cases: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. This clearly indicates when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds value by disclosing exactly what will be returned (fields, geometry type, record count, capabilities), which goes beyond the annotations and gives the agent a good sense of the tool's output.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and enumerates the return value details efficiently. Every word earns its place with no redundancy.

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

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

For a simple 1-parameter tool with strong annotations, the description is complete: it states what the tool does, how it is invoked (by URL), and what information the agent can expect to receive. There is no output schema, but the description itself provides the necessary outcome details, making it sufficient for the agent to decide correct usage.

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

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

The input schema already provides a description of the url parameter with an example. The description's mention of 'by url' adds minimal semantic meaning beyond what the schema already provides, so the baseline of 3 is appropriate given 100% 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 states a specific verb ('Get') and a specific resource ('ArcGIS Feature/Map Service layer's schema'), and explicitly lists the key information returned. This clearly distinguishes it from sibling tools like query_layer, which presumably queries actual data.

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

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

The phrase 'by url' clearly indicates that the tool requires a layer URL and is meant for retrieving schema metadata. It does not explicitly name alternatives or state when not to use it, but the context is reasonably clear given the described purpose.

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, non-destructive, idempotent behavior. The description adds value by disclosing the return field list, caller scoping ('caller's'), and the active-only default, all 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?

Two concise sentences. The first states the action and return fields; the second provides usage guidance. No filler or redundant 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?

For a simple list tool with one optional parameter, the description covers scope, return fields, and use cases. Annotations handle safety. No important gaps apparent.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, and the schema description is clear. The tool description does not add parameter-specific semantics, but the baseline of 3 is appropriate given the schema does the heavy lifting.

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 lists the caller's active subscriptions, uses a specific verb ('List') and resource, and enumerates the returned fields. It distinguishes itself from subscription-related siblings by framing use cases (reviewing before adding more, finding an id to cancel).

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

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

Provides explicit when-to-use context: 'review what you're monitoring before adding more' and 'find an id to cancel.' This implies alternatives (subscribe/unsubscribe) without naming them explicitly, 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 are all false, so the description carries the full burden. It discloses the non-account claim_token return, how to check status later, rate limiting ('5 per identifier per day'), and that it doesn't count against tool-call quota. It also clarifies that feedback is read daily and influences roadmap, giving a clear picture of side effects.

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, every sentence earns its place: purpose, eligibility, exclusions, token flow, rate limit, and quota impact. It is front-loaded with the main purpose and then logically flows through instructions. No redundant or vague wording.

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-mode tool without an output schema, this description is highly complete. It explains what happens when filing (returns claim_token), how to retrieve status later, what the team does with feedback, and practical constraints (rate limit, quota). No critical operational context is missing.

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

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

Schema coverage is 100% with rich per-parameter descriptions. The description adds value by explaining the two invocation modes: filing (type/context/message) vs. reading a claim (claim_token alone with no other arguments). It also reinforces that context should reference Pipeworx tool/pack names, which goes 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 a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature/data_gap, praise) and distinguishes itself from sibling research/subscription tools. The dual-mode behavior (filing vs. claiming with a token) is also explained up front.

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 a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'when something worked surprisingly well') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It also warns against pasting end-user prompts and explains the claim_token follow-up workflow.

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, and non-destructive. The description adds meaningful behavioral context: it is a self-aggregating signal derived from CF analytics-engine, states 'no PII, just (pack, tool, count)', and discloses caching (5min-1h depending on window)—all 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 a single paragraph with a clear purpose statement followed by a 'Useful for:' list and provenance note. All sentences contribute, though the list could be slightly trimmed without losing value.

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

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

With no output schema, the description states the return content (top tools, top packs, total call volume) and clarifies the data shape as '(pack, tool, count)'. It also covers caching and data source, making it complete for a 1-param read-only tool.

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

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

The input schema fully covers the only parameter 'window' with its enum values and trade-off explanation. The tool description adds no additional parameter semantics beyond mentioning the window, so with 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Returns') and resource ('top tools, top packs, and total call volume'), and frames it specifically as 'what other AI agents are calling on Pipeworx right now.' This distinguishes it from sibling tools like discover_tools by emphasizing the aggregated, social-signal aspect.

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 'Useful for:' list provides three explicit use cases, and the window guidance contrasts short vs long windows. However, it does not explicitly name alternative tools or state 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond this by disclosing internal logic such as monotonicity/partition-sum checks, Jaccard similarity threshold (≥0.30), placeholder filtering (>20% returns null), and fill-check behavior (realizable_edge_pp ≤0 means 'do not trade it'). It also describes response fields and edge cases, adding rich context without contradicting 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 lengthy but each sentence contributes necessary detail for a complex tool. It is front-loaded with purpose and invocation modes, but could be more scannable with structured lists or bullet points. Still, no sentence feels wasted, so it earns a high score.

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

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

With no output schema, the description must explain return values, and it does: opportunities[] with fields, partition_check structure, and fill_check details. It also covers filtering logic, skipped_low_similarity, and references a sibling tool for custom sizing. All invocation modes and edge cases are addressed, making it highly complete.

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

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

Schema coverage is 100% for both parameters, but the description adds substantial meaning: it defines event slugs with concrete examples ('fed-decision-may-2026'), topic seed questions ('Strait of Hormuz traffic returns to normal'), and behavior of each mode. This goes far beyond the schema's basic descriptions, helping the agent choose and format parameters correctly.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', using a specific verb and resource. It clearly distinguishes this from sibling tools by detailing event and topic modes and referencing polymarket_fill_risk for custom sizing, making its unique purpose obvious.

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 explains three invocation modes: no args for trending_scan, event for single-event checks, and topic for cross-event scans. It contrasts single-event vs cross-event capabilities and points to polymarket_fill_risk for custom sizing, providing clear when-to-use and alternatives 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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail beyond that: it explains the return structure (by_segment, fed_candidates, _diagnostics), the caching behavior (Cached 1h at the KV level keyed on all knobs), the per-leg slippage assumption, the 24h-move warning, and the internal model families. It also explains why segments can be empty, which is valuable for callers. No contradictions with annotations.

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

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

The description is long, but it is densely packed with unique, valuable information structured by segments and knobs. It front-loads the core purpose and then systematically details the three model families, response fields, and filters. There is little redundancy, and every sentence contributes context. It could be more parsimonious, but the complexity of the tool justifies the length.

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?

Since there is no output schema, the description carries the full burden of explaining the return value structure. It thoroughly describes the top-level response (by_segment with three named keys, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips). It also explains the meaning of each opportunity field (e.g., edge_pp_net after slippage, kelly_fraction capped at 0.25). This is complete for a complex tool with no 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?

The input schema already has 100% description coverage for all 9 parameters, so the baseline is 3. The description adds extra context that enriches the schema, such as explaining that min_kelly does not filter partition_overround opportunities because partition-level kelly_fraction_half is always 0 by design, and explaining the rationale behind min_liquidity and max_spread_pp. This goes beyond simple parameter descriptions, 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and distinguishes it from siblings like polymarket_arbitrage (which likely focuses on cross-market arbitrage) and polymarket_edge_tracker (which tracks edges over time). The phrase 'Built for what should I bet on today' adds a clear use case.

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

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

The description explicitly states the intended use case ('what should I bet on today') and provides guidance on how to use the knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also notes a caveat about Fed bets being excluded from ranking. However, it does not explicitly contrast with alternative sibling 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 annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral context: 60-day snapshot TTL, snapshots written on cache-miss causing gaps, decay computed from daily closes not intraday, and detailed response semantics. This enriches the safety profile without any contradiction.

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

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

The description is well-structured with clear sections for arguments, response, and limits. It is front-loaded with the core question, and every sentence provides meaningful information. Despite its length, it remains efficient and readable.

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

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

With no output schema, the description thoroughly explains the return value (tracked[], expired[], snapshot_dates[]) and their meanings, including derived metrics and caveats. It also covers data freshness and TTL limits, making the tool fully understandable without external references.

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 complete descriptions for both parameters (defaults, clamps, allowed values), and the description largely repeats these details. It adds 'snapshot family' context for window but no significant new semantics, 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 clearly identifies the tool as providing 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series rather than current edge values.

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 context by noting it is 'built from daily polymarket_edges snapshots', suggesting it is for historical persistence/decay analysis versus the current-edge tool. However, it does not explicitly name an alternative tool or state when not to use it, 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?

The description provides extensive behavioral context beyond the annotations: it details the ladder-walking computation, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), mode-specific interpretation of size_usd, and the failure mode of partial basket fills ('convert an arb into an unhedged directional position'). It also warns about thin books and lists forced_directional_risk as a return. Annotations only state readOnly/idempotent; the description adds far more.

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 highly structured with bolded mode indicators (SINGLE-MARKET, BASKET) and a direct 'USE THIS' instruction. Every sentence adds functional value, and content is front-loaded with purpose. It loses a point for sheer length, but the organization makes it 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?

In the absence of an output schema, the description fully enumerates all return values for both modes, explains the interpretation of results (e.g., theoretical_sum vs realizable_sum, capture_ratio, profit_usd), and contextualizes the tool's place in a workflow. It even names the specific sibling signals it should precede. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and the schema descriptions are already detailed. The description adds critical non-obvious semantics: the requirement of exactly one of `market` or `event`, the default of `side` in basket mode ('auto from partition sum'), and how `size_usd` is interpreted differently in each mode. This boosts the value above schema baseline, though the schema itself already covers some of the same semantics.

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

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

The description opens with a precise statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This uses a specific verb ('check') and resource ('live CLOB order-book depth'), and clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk verification rather than trade discovery or execution.

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

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

Explicit guidance is embedded: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market mode vs basket mode, and clarifies the downside of not using it (partial fills → unhedged directional risk). This is model guidance for when to choose this tool and when not to.

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 establish a safe read-only profile, and the description goes far beyond it by disclosing the matching algorithm, fee caveats (gross spreads, Kalshi fees not modeled), interpretation of null temporal_alignment, and compatibility codes. These are behavioral traits an agent could not infer from annotations alone. 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?

Long — roughly 300 words — but nearly every sentence carries a safety-relevant caveat or defines a flag, which is justified given the absence of an output schema. It is front-loaded with purpose and modes. The density makes it harder to scan quickly, but the all-caps section labels help.

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?

Because there is no output schema, the description carries the full burden of explaining the response: leg prices, top_spreads_pp, compatibility fields, flags, skipped categories, confidence pairs, temporal alignment, and fees. It leaves no decision-relevant behavior ambiguous.

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 this dimension starts at baseline 3. The description adds value by explaining the interaction between parameters ('overrides the topic-mapped side'), giving real ticker/slug examples, and stating that explicit mode uses the same matcher as topic mode.

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?

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which precisely names the resource, the two venues, and the comparison being made. This is distinct from any sibling tool, including Polymarket-only tools like polymarket_edges.

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

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

Clearly distinguishes the two invocation modes — pre-mapped 'topic' shortcuts vs explicit 'kalshi_event_ticker' plus 'polymarket_event_slug' for custom pairings — and warns that most pre-mapped topics currently return compatibility_warning. It does not name alternative sibling tools or explicitly say when not to use this tool, so it misses the top bar.

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, so the safety profile is covered. The description adds behavioral context by specifying the return type ('attribute rows (and geometry)') and the SQL-like query nature. No contradictions with annotations exist.

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 resource, and every clause earns its place. It conveys the core functionality, a usage pattern, and a sampling tip without any 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 tool with 6 parameters and no output schema, the description covers the essential workflow (query layer by URL, return rows/geometry) and links to search_datasets. While it does not detail pagination or error handling, the schema already documents `offset` and `limit`, making the description sufficiently complete for an agent to start using 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 input schema provides 100% coverage for all 6 parameters, so the baseline is 3. The description adds a convenient usage pattern for `where` and `out_fields`, but it does not clarify individual parameter semantics beyond what the schema already contains. The 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 states a specific verb ('Query') and a specific resource ('ArcGIS Feature Service / Map Service layer'), clearly distinguishing it from sibling tools like layer_info (metadata) and search_within (spatial). It also specifies the source ('from search_datasets'), making the tool's role 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 implies a workflow by referencing 'from search_datasets' and gives a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly exclude alternatives or state when not to use this tool in favor of siblings like layer_info or search_within, leaving room for clearer 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 and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: scoping to an identifier (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieving a single key vs listing all keys. This goes beyond the schema and annotation baseline, though it doesn't address potential edge cases like empty memory or error handling.

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, all information-dense with no redundancy. The main action is front-loaded, followed by usage context, scoping, and sibling relationships. Every clause 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 one-parameter read-only tool, the description covers both operational modes, explains scoping, and situates it within the memory workflow (remember/forget). Given the rich annotations and schema, no critical information is missing. The lack of return format details is acceptable since no output schema exists and the tool's behavior is straightforward.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by explicitly stating 'omit the key argument' and provides concrete examples of key values (user's target ticker, address, research notes), which helps the agent understand what constitutes a meaningful key. This adds value beyond the schema alone.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes itself from siblings by explicitly referencing remember and forget, making the tool's role within the memory system 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?

Explicit guidance is provided: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the counterparts (remember, forget) and clarifies the omit-key behavior for listing all keys, giving the agent clear when-to-use and alternative context.

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

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

The description states that setting mark_read:true flags events as read, which modifies state, directly contradicting the readOnlyHint annotation that declares the tool read-only. This is a clear annotation contradiction, so the score is 1 per the rubric.

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

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

The description is three sentences, front-loaded with the core purpose. It packs substantial detail into each sentence without fluff. The second sentence is somewhat dense but remains readable and all content is relevant.

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 return payload, filtering, mark_read side effect, polling, and an alternate HTTP access point. It omits nothing critical, and the schema covers remaining parameter details. It would be complete if not for the transparency contradiction.

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?

While the schema covers all parameters at 100%, the description enriches meaning by giving a concrete example for type (sec_8k), specifying ISO timestamp for since, and explaining the side effect of mark_read. This goes 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 'Pull fired events from your subscription feed,' which specifies a clear verb, resource, and scope. It distinguishes itself from sibling tools like list_subscriptions by focusing on fired alert events, and adds details about the payload and filtering.

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: filtering by type and since, mark_read behavior, and polling suitability. It also names an alternative endpoint for scripts/dashboards, offering an explicit alternative. It does not explicitly exclude sibling tools, but the guidance is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond this: it details the fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), explains fallback logic for rate limiting (GNews when GDELT fails), and notes soft-fail for patents due to API sunset. This is exactly the kind of behavioral depth annotations alone cannot 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?

Despite its length, every sentence serves a purpose: the opening lists real-world query examples, the middle covers sources and fallbacks (including the PatentsView sunset caveat), and the closing explains return format and alternative tool. The information is front-loaded with purpose, and the structure is logical. There is no filler or redundant repetition beyond what schema already provides for parameters.

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

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

The tool has no output schema, yet the description clearly specifies the return shape: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers the multi-source fan-out, fallback behavior, and the distinction from entity_profile, making it complete for an agent to decide when to invoke this tool and what to expect.

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

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

Schema description coverage is 100% and the schema already explains each parameter thoroughly (e.g., 'since' format and typical usage). The description mostly repeats this information rather than adding new meaning. It adds context about the overall window ('last N days/weeks/months') but does not materially enhance parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as a change feed for a company, with explicit examples of user queries ('What's new with X', 'latest on Y'). It distinguishes itself from sibling tools by naming entity_profile as the alternative for static profiles, making the scope and resource type 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 usage scenarios and parameter guidance (e.g., 'since' with formats and typical values). It also explicitly names entity_profile as the alternative when static profile data is needed, offering clear exclusion criteria. The fallback behavior between GDELT and GNews is disclosed, helping the agent set expectations.

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

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

Annotations already signal read/write and idempotence, but the description adds valuable context: key-value scoping by agent identifier, persistence differences for authenticated vs anonymous sessions (persistent vs 24-hour retention), and pairing with recall/forget. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the core function, followed by usage guidance and storage behavior. No redundant wording; every sentence earns its place. It efficiently communicates what, when, and how without excess.

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

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

For a simple two-parameter write operation with no output schema, the description fully covers what the tool does, when to use it, persistence semantics, and relationship to siblings. Nothing critical is missing; the complexity is low and the description is proportionate.

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

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

Schema description coverage is 100% for both parameters (key and value), so the schema already provides full technical detail. The description only adds real-world examples of content to store, which is helpful but not parameter-level semantics. This matches 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes this tool from siblings by naming paired tools (recall, forget) and giving concrete use-case examples (ticker, address, preference, research subject). This makes 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?

It explicitly states when to use the tool ('Use when you discover something worth carrying forward... so you don't have to look it up again') and names the complementary tools for retrieval and deletion. Though it doesn't list negative use cases, the guidance is clear and actionable enough to prevent misuse.

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, and the description adds substantial behavioral context beyond them: internal cascading through multiple lookup endpoints, graceful degradation if GLEIF/OpenFIGI is unavailable, returning figi_candidates without asserting on ambiguity, labeling identifiers with sources, and explicitly listing unresolved identifiers in an `unresolved` field. None of this contradicts 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 extremely dense but poorly structured — one long run-on paragraph with semicolons, especially the 'company' type section, making it hard to scan. Front-loading is decent (examples + 'Use FIRST'), but the sheer length and lack of bullet points or section breaks hurt readability. Every sentence carries value, but the organization does not.

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 carries full responsibility for return behavior, and it delivers: it covers identifiers per type, ambiguous matches via figi_candidates, unresolved fields, source labeling, drug citation format, and degradation behavior. Input constraints and edge cases (e.g., bond names, non-US issuers) are also specified. Very little an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description massively enriches parameter meaning: the `value` parameter gets precise input constraints (pass entity name only, never the full noun phrase, bond issuer as printed) and the `type` parameter is expanded with detailed return behavior and examples. This goes far beyond the terse 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 explicit query patterns and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly differentiates itself from sibling tools by positioning itself as the ID-resolution layer that feeds other tools, which is distinct from entity_profile, compare_entities, and the research tools.

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

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

Gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also provides nuanced when-to-use details for ambiguous bond names and non-equity instruments. However, it never names a specific alternative tool for when this tool is NOT appropriate, so the when-not guidance is only implied rather than explicit.

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 claim read-only, idempotent, open-world, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. This provides useful context for how the tool operates without contradicting 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 three sentences, front-loaded with the action and differentiated purpose. Each sentence provides distinct value: method, use case, and output format. The quoted example is concise and helpful, not wasteful.

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 compensates by specifying the return structure (ranked list with score, confidence, signal density). Parameters are fully covered by schema, and annotations cover safety. It could mention rate limits or auth details, but the schema already covers the _apiKey parameter, making this sufficient.

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

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

Schema coverage is 100% and each parameter has detailed descriptions, so the baseline is 3. The description does not add significant parameter meaning beyond echoing the entities concept, while the schema already explains first-entry-as-subject and model/API key constraints.

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 ('Compare'), a specific resource ('AI visibility across multiple entities'), and explicitly distinguishes from the sibling ai_visibility_check by indicating it probes each entity and ranks by score. The tool's purpose is 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 a clear use case for competitive AI-marketing audits and explicitly contrasts with ai_visibility_check by describing how it probes each entity. However, it does not mention alternatives such as compare_entities or state when not to use the tool, 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?

Beyond the read-only and idempotent annotations, the description discloses behavior such as fanning out across two services, partial failure degradation, and the 5-30s latency for bundlephobia's first measurement. It also explains the 'sources_failed' output when timeouts occur. This adds significant behavioral context that annotations alone do not 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 serves a purpose: purpose, use cases, output summary, ecosystem scope, and failure handling are clearly delineated. It front-loads the primary function and avoids fluff. Despite its length, it remains well-structured and scannable.

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

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

For a composite tool with no output schema, the description fully accounts for complexity: it lists the exact output fields, describes per-advisory detail and links, explains ecosystem limitations, and covers failure modes with graceful degradation. This is complete enough for an agent to confidently invoke the tool and interpret 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?

The input schema already provides complete descriptions for both parameters (package name and version). The main description adds only a brief mention of scoped packages and default-to-latest behavior, which is already implied by the schema. Since schema coverage is 100%, the description adds minimal extra value for parameter semantics, aligning with the baseline of 3.

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

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

The description opens with a specific verb and resource: "Composite 'should I add this npm package to my project' check in ONE call." It clearly distinguishes the tool from siblings by naming the external data sources (deps.dev, bundlephobia) and the exact question it answers. This makes its purpose unambiguous and unique among the listed sibling tools.

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

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

The description explicitly states when to use the tool: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also gives an exclusion criterion for non-NPM ecosystems, directing users to "deps.dev:version directly" for PyPI/Maven/Cargo/Go. This provides clear context and a fallback 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, and non-destructive, so the safety profile is covered. The description adds exact return fields (name, summary, record_count, owner/org, Feature Service url) and explains how to use the returned url, going beyond annotations.

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

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

Two sentences with no fluff. First sentence states purpose and scope; second lists return fields and chaining. Front-loaded and efficient.

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

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

For a search tool with 3 optional params and no output schema, the description covers the core: what it searches, what it returns, and how to use results. It also accounts for sibling tools by pointing to query_layer/layer_info. No significant gaps.

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

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

Schema describes all three parameters with clear descriptions (query, limit, org_id), so the baseline is 3. The description adds minimal parameter semantics beyond 'by keyword', but it does not conflict with schema and provides contextual scope.

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

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

The description uses a specific verb ('Search') and names the exact resource ('City of Johnson City GIS open geospatial datasets') with examples of scope ('parcels, zoning, public works & city services'). It clearly distinguishes from sibling tools like query_layer by stating it returns Feature Service URLs for further querying.

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 tells the agent what to do with the results ('pass that url to query_layer / layer_info'), giving clear guidance on when to use this tool versus alternatives. The chaining instruction implies this tool is for discovery, while query_layer/layer_info are for data access.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond these flags: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. 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 longer than minimal but every sentence contributes: purpose, use case, pairing with sibling tool, and technical details. It is front-loaded with the core semantic search action, then explains why to use it, and ends with implementation specifics. 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?

With no output schema, the description bears responsibility for explaining return values, which it does explicitly: 'top-N passages with character offsets and similarity scores.' It also covers the full context: when to use, technical implementation, input limits, and integration with ask_pipeworx_grounded. This is a complete picture for a semantic search tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'), clarifying the type of text expected (SEC 10-K, article, long tool result), and mentioning the 200K char limit. This goes beyond the schema descriptions and helps the agent craft appropriate inputs.

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 ('semantic search') and resource ('a fetched record') with explicit scope ('INSIDE a fetched record'). It gives concrete examples (SEC 10-K body, article) and clearly differentiates from broader search tools by focusing on searching within already-fetched text, not external 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?

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also explains the tradeoff (saves context) and pairs with ask_pipeworx_grounded, describing the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear usage context and relationship to an 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?

The description discloses several behavioral traits beyond the annotations: requires an OAuth account, phone verification for SMS, a 10/day SMS cap, and the always-on feed behavior. These details add real-world constraints and side effects that the annotations alone do not 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 dense but well-structured: it leads with the core purpose, then requirements, supported types, and delivery options. Each sentence delivers necessary information without fluff, making it appropriate for a tool with multiple types and delivery modes.

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 essential aspects: purpose, return value, authentication requirements, supported types, and delivery channels. The main omission is webhook as a delivery channel in the main description, though the schema thoroughly documents it. Given the tool's complexity and lack of an output schema, it is nearly complete, but the webhook omission could mislead an agent reading only the description.

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

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

The description enriches the schema by providing concrete examples for each supported type (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and clarifying delivery channel behavior. Even with 100% schema coverage, these examples add meaningful context that goes beyond the raw parameter descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. This specific verb+resource combination distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

It gives explicit prerequisites (Pipeworx OAuth account, verified phone for SMS) and clarifies that anonymous/BYO cannot persist subscriptions. It also explains the always-on feed and how to retrieve alerts via recent_alerts, providing good usage context. However, it does not explicitly state when not to use this tool or contrast it with alternatives like list_subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond that: it describes the return format (category-bucketed example questions), the source (live catalog of thousands of tools), and the effect of the topic parameter (focus vs. full spread). This gives the agent a clear picture of what to expect without any 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 dense but every sentence earns its place. It front-loads example queries, then explains the output and parameter behavior, and ends with direct usage guidance. The structure uses clear separators and examples that make it easy to scan. Despite its length, there is 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?

For a tool with only one optional parameter and no output schema, the description is exceptionally complete. It explains the purpose, the exact output structure (categories, examples, tool+argument shape), how to control scope, and when to use it. It even names related meta-tools to learn, giving the agent full context for onboarding. There is no missing information that would prevent correct invocation.

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

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

Schema coverage is 100% and the schema already describes the topic parameter with a list of focus areas. The description goes further by giving concrete examples ('finance', 'pharma', 'betting') and explaining the behavioral difference between omitting and providing the parameter (full spread vs. focused). This reinforces and enriches the schema description, adding real-world context that helps the agent select appropriate values.

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 what the tool does: it is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses a specific verb ('suggest questions') combined with a resource ('Pipeworx capabilities') and distinguishes it from siblings by focusing on 'what can I ask' rather than tool discovery. The clarification that it also teaches how to call meta-tools further sets it apart.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', giving a clear when-to-use condition. It also explains how to tailor usage (no args for full spread, topic to focus) and mentions alternative meta-tools to learn about. However, it does not explicitly state when not to use the tool (e.g., once you already know what to ask), so it falls slightly short of a perfect 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 indicate this is a write, non-destructive, idempotent operation. The description complements this by clarifying that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. It also reveals ownership enforcement, which is not captured 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 three concise sentences, front-loaded with the action, then detailing constraints and consequences. No filler; every sentence provides essential information.

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

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

For a simple single-parameter mutation, the description covers purpose, ownership, and the soft-delete behavior. Coupled with strong annotations and complete schema, it is fairly complete. It doesn't specify return values or error conditions, but the absence of an output schema and low complexity reduces the burden.

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 the id parameter (uuid returned by subscribe), so the description adds little new information about parameters. The schema description coverage is 100%, so a baseline score of 3 is appropriate; the description's 'by id' reinforces the parameter without adding new semantics.

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

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

The description opens with 'Cancel a subscription by id,' which clearly specifies the verb (cancel), resource (subscription), and scope (by id). It also adds ownership enforcement, distinguishing it from general subscription management tools like subscribe and list_subscriptions.

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

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

It provides clear context by stating ownership is enforced and that the subscription is deactivated rather than deleted, implying when to use it (when you want to cancel your own subscription and preserve history). However, it does not explicitly mention alternatives like list_subscriptions or explain when not to use it beyond ownership.

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/idempotent annotations, the description discloses critical behaviors: the SEC EDGAR fast path, grounded-pipeline fallback, and the exact semantics of verdicts. It especially clarifies the distinction between could_not_verify (system failure, not evidence) and unsupported (no source), which is essential for correct agent behavior.

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

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

The description is dense but every sentence serves a purpose: examples, routing logic, verdict semantics, error handling, and efficiency gain. It is well-organized and front-loaded with the most actionable trigger phrases, making it easy for an agent to parse and apply.

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

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

Given the tool's complexity (multiple verdicts, two execution paths, error cases), the description covers all key aspects: return values, citations, reasoning, and the crucial caller instruction about could_not_verify. Even without an output schema, the agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaningful context: claim is the natural-language input with examples, and tolerance_pct's default and override semantics are explained, including a practical use case (set 1–2 for hallucination detection). This enriches the schema beyond plain parameter names.

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

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

The description identifies a specific verb+resource: claim verification against authoritative sources, with natural-language examples and a clear deliverable (verdict). It distinguishes itself from sibling tools by framing the task as fact-checking with structured verdicts and a two-path pipeline.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company financial claims vs. other claims, and notes that it replaces 4–6 sequential calls, effectively contrasting with alternative approaches.

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