Arcgis Richmond

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

Annotations already flag readOnly/idempotent/non-destructive; description adds behavioral context about default model being free, the BYO Anthropic key cost implication, and the per-model response shape. These details go beyond the annotations and help set expectations.

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 tightly written sentences: action+output, model/cost behavior, and use cases. Front-loaded with the core purpose and no redundant phrasing.

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 explains the return format (per-model score/confidence/signals/raw_response + combined view). It covers model selection, cost, and use cases, making it fully self-sufficient for an agent to decide and invoke.

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

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

Schema covers 100% of parameters, but the description enriches semantics by clarifying the default model when 'models' is omitted, and that '_apiKey' is passed straight through to Anthropic with direct billing. It connects the parameters to real-world usage.

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

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

Description opens with a specific verb+resource: 'Probe one or more LLMs...' and defines the outcome (score visibility 0-100 per model). The scope (business/brand/product/topic) and return structure are clearly stated, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. However, it doesn't mention alternatives or when not to use this tool compared to siblings.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds valuable behavioral context beyond that: it routes questions to the appropriate tool, fills arguments, returns structured answers with stable citation URIs, and works on every tier. This gives agents a clear model of what will happen when invoked.

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: domain list, routing mechanism, usage triggers, examples, escalation paths, and special handling for breaking news. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and uses clear separators to organize guidance.

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

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

For a tool with such broad scope and complex routing, the description is remarkably complete. It covers what the tool does, when to use it, how it behaves, what output to expect (structured data with citations), and how it compares to siblings. No output schema exists, so the description effectively substitutes by promising structured answers, which is a key detail.

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 'question' as natural language with multiple aliases. The description only adds example questions, which are already present in the schema's examples. It does not introduce new parameter semantics or clarify edge cases.

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

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

The description clearly states it answers factual questions by routing to one of 5,462 tools across 1,419 verified sources, returning structured answers with pipeworx:// citations. It explicitly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance with a long list of example domains and question phrases, plus a strong directive to 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It also clearly names alternatives for specific cases (grounded for verbatim evidence, deep_research for broad/multi-part questions).

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses experimental behavior: 'candidate routing improvements enabled live whenever one is under test' and notes that no candidate is currently active, so it currently matches ask_pipeworx exactly. It also reassures that it 'falls back to nothing — this IS a full working router,' adding valuable runtime context.

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

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

The description is front-loaded with the beta identity and provides essential context about candidate status and comparison to the stable router. It is slightly dense but each sentence contributes useful information without waste.

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

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

For a complex beta router with no output schema, the description fully explains what it is, how it differs from the stable version, the current active state (no candidate), and that it is a fully functional router with identical response shape. This gives the agent enough context to invoke it correctly.

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

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

The schema covers all parameters with 100% description coverage (including aliases for 'question'), and the description adds no parameter-specific semantics beyond noting 'same arguments' as ask_pipeworx. Since the schema does the heavy lifting, a 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 explicitly identifies the tool as a 'Beta version of ask_pipeworx' and describes it as an 'identical universal router (same 5,462 tools, same arguments, same response shape)' with 'candidate routing improvements' – this clearly states what it does (routes queries to tools) and distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded 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?

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that 'results are compared against the stable router to decide what merges,' giving a clear condition for when to use this beta variant over the stable one.

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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial context: refusal reasons, evidence extraction, one extra LLM call cost, and explicit refusal modes. This goes well 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 front-loaded with the core purpose and is dense with valuable information. It is somewhat lengthy but each sentence adds meaningful detail (cost, return structure, use cases), so it earns a 4 rather than a 5.

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

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

With no output schema, the description compensates by fully explaining the return structure (answer, evidence, confidence, etc.) and all possible refusal reasons. It also covers the tool's relationship to alternatives and cost, making it complete for a high-stakes 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%, with all six parameters being aliases for 'question' thoroughly documented. The description itself does not add parameter-level semantics, but the schema already covers them, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb phrase 'hallucination-resistant answer mode' and clearly identifies the resource (Pipeworx). It explicitly distinguishes from sibling 'ask_pipeworx' by noting the same routing but extraction from tool result only, making its unique purpose clear.

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

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

Provides explicit when-to-use guidance (high-stakes reads, quoted/cited/acted on) and when-not-to-use ('prefer ask_pipeworx for casual lookups'). Names the alternative tool directly, fulfilling the dimension fully.

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

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

Goes well beyond the readOnly/idempotent hints: describes blocking statuses (low_confidence_match, market_closed_or_inactive), fallback behavior for news (GDELT 429s → GNews backfill with retry_after_sec), error suppression for safety, wide-spread illiquidity flag, cancellation-rule parsing, and 24h-move warning. 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?

Heavily structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. The length is substantial but every section addresses a real agent need (safety, resolver contract, news fallbacks). A few example details could be trimmed, but clarity is high.

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

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

No output schema, so the description compensates by enumerating market/analysis/evidence shapes, resolver match fields, parent-event extraction, news fallback fields, safety statuses, and cancellation-rule risk—covering both normal and edge cases comprehensively.

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

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

Schema already has 100% coverage with clear descriptions for market, depth, include_raw. The description adds fan-out context and response shapes but doesn't elaborate on parameter formats beyond schema, so baseline 3 is fair.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' — a specific verb, resource, and scope that distinguishes it from siblings like polymarket_edges and validate_claim. Also lists exact use cases ('should I bet on X') and classifiers, making 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?

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and details fan-out examples per classifier. However, it doesn't explicitly name alternative tools to prefer when these conditions don't hold, so it's clear but not fully exclusionary.

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 and idempotentHint, and the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 dense but every sentence contributes value: trigger phrases, the preference rule, entity-specific data, sorting behavior, and output details. It is front-loaded with user-facing examples and avoids redundancy with the schema.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (paired data + citation URIs), how results are ordered, and what data sources are used per entity type. This gives the agent enough context to invoke and interpret results 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?

While the schema already documents both parameters with examples, the description enriches meaning by detailing exactly what fields are pulled for 'company' (revenue, net income, cash, long-term debt) and 'drug' (FAERS counts, FDA approvals, trials), going beyond the schema's basic enum and array 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 identifies the tool's purpose with a specific verb ('compare') and resource ('companies or drugs') and includes trigger phrases like 'X vs Y' and 'which is bigger.' It explicitly distinguishes from sequential single-pack lookups, naming the alternative approach, which differentiates it from siblings like entity_profile.

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

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

Provides explicit guidance on when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also spells out the types of queries that should invoke it and what data each entity type retrieves, giving clear contextual boundaries.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses many behavioral traits: account and plan requirements, parallelization across 5,462 tools, return packet contents (verbatim evidence, confidence, source, fetched_at, citation), gaps[] and contradictions[] behavior, semantic excerpting, and expected latency (15-60s, up to 90s for thorough). It also states it 'never invented' answers and gives conditions for empty gaps. No contradiction with annotations.

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

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

The description is lengthy but dense with high-value information. It front-loads the critical account requirement and then logically covers purpose, alternatives, depth semantics, output details, and performance. Some redundancy exists (e.g., contradictions[] mentioned twice), but every sentence earns its place for a complex tool. It could be trimmed slightly but is appropriately structured for its complexity.

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

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

No output schema exists, so the description bears full responsibility for explaining return values—and it does thoroughly: findings packet with evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers latency, account tiers, and alternatives. For a complex research tool with two params and rich behavior, this is comprehensive and complete.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaningful context beyond the schema: it explains that question can be 'Broad/multi-part' and clarifies depth levels with concrete behavioral differences ('standard re-angles unanswered gaps', 'thorough additionally chases the best leads'), plus notes the paid plan requirement for thorough. This adds useful nuance to the depth enum that the schema alone doesn't convey.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' with decomposition and parallel routing. It distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx: 'For a single lookup use ask_pipeworx instead.' The verb+resource+scope is specific and unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' as well as 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also covers account prerequisites and tier restrictions: 'ACCOUNT REQUIRED... depth:"thorough" needs a paid plan.' This gives clear selection criteria against siblings.

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

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

Annotations already cover readOnly, idempotent, and non-destructive safety. The description adds valuable behavioral context: returns top-N tools with names, descriptions, full input schemas, and examples, and emphasizes results are ready to call without a second schema lookup. No contradiction with annotations.

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

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

Three sentences: purpose, domain coverage, and return/usage behavior. Front-loaded and every sentence carries information without redundancy.

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

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

For a discovery tool with no output schema, the description fully covers return value (names, descriptions, schemas, examples), call behavior (directly callable), and usage priority (call first). No meaningful gaps remain.

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

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

Schema coverage is 100% with descriptions for all six params, so the schema does the heavy lifting. The description adds light value by explaining the query parameter is a natural language description and providing example queries, but doesn't go beyond the schema's own clarity.

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

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

Clearly states 'Find tools by describing the data or task' with a specific resource (the tool catalog). It distinguishes from siblings by explicitly saying 'Call this FIRST when you have many tools available' and listing covered domains, making its unique 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?

Provides explicit context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...'. It lacks named alternatives, but the 'not just one answer' contrast hints at when not to use it, so it's clear without 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 mark the tool as read-only and safe, so the description's extra context is valuable. It discloses parallel fan-out behavior, data sources (SEC, XBRL, USPTO, news, GLEIF), a known failure mode ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and return fields, adding meaningful behavioral detail beyond the annotations.

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

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

The description is long but densely packed with necessary information for a multi-source tool; every clause earns its place. It is front-loaded with example queries and purpose, followed by return details and caveats. Slightly heavy as a wall of text, but efficient given the complexity.

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

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

With no output schema, the description explicitly lists return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and handles edge cases (patent API sunset, name unsupported). Given the tool's complexity, this description provides a complete enough picture for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and already documents both parameters well. The description enhances this with concrete examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') and reiterates the name constraint, adding practical guidance that goes beyond the schema's own 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 example queries and then states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from alternatives by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups,' making its unique scope clear.

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

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

The description gives direct usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states exclusions ('names not supported — use resolve_entity first if you only have a name') and input constraints, effectively telling the agent when to use this tool vs. 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 destructiveHint=true and idempotentHint=true, so the safety profile is well-covered. The description adds qualitative context (e.g., clearing sensitive data) but no new behavioral mechanics 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 sentences, front-loaded with the core action, and no redundancy. Every word contributes either to defining the action or guiding usage.

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

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

Given the tool's simplicity (one parameter, no output schema) and robust annotations, the description fully covers purpose, usage scenarios, and related tools. No additional details are needed for safe and effective invocation.

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

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

The input schema provides 100% coverage for the single parameter 'key', including its type and description. The tool description adds no further meaning beyond the schema's own documentation, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'), which precisely defines what the tool does. It also differentiates from siblings by referencing its role in the memory lifecycle relative to remember and recall.

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

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

Explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It also names companion tools (remember and recall), providing clear alternatives and context for effective selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond that by explaining that it fetches the page, extracts content, and emits markdown. This gives the agent an accurate picture of the tool's side effects (network fetching) and output shape 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 core purpose, then explains the process, and ends with concrete use cases. Every sentence adds value with no filler or repetition of schema/annotation 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 tool with two simple parameters, no output schema, and strong annotations, the description is complete. It explains what the tool does, how it works, what output to expect, and when to use it. 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%, so both parameters are fully documented in the schema. The description does not add meaning specific to max_links or url beyond what the schema provides, so a 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 states a specific verb+resource combination: 'Generate a production-ready llms.txt file for any URL'. It further details the process (fetches page, extracts title/description/key links) and output format, clearly distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('Useful for: 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'). It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing what the call returns (fields, geometry type, record count, capabilities), which is behavioral context not present in the annotations. No contradictions.

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

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

The description is a single, front-loaded sentence that packs in the verb, resource, and output details with no wasted words. It is concise and well-structured.

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

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

For a simple single-parameter tool with robust annotations, the description is complete. It lists all key output components, making it sufficient even without an output schema. 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 description coverage is 100% for the one parameter (url), including an example. The description merely mentions 'by url' without adding extra detail beyond the schema, so it meets the baseline but does not enhance parameter understanding.

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 ('Get') and clearly identifies the resource (ArcGIS Feature/Map Service layer's schema) and the exact data returned (fields, geometry type, record count, capabilities). This fully distinguishes it from sibling tools like query_layer.

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 a clear use case: when the user needs schema metadata for a layer, not its data. It provides context by specifying the output, but does not explicitly name alternatives or say 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 declare read-only, idempotent, and non-destructive behavior. The description adds the specific return fields and default scope of active subscriptions, but no additional behavioral context such as rate limits or pagination. This aligns with the calibration example where annotations cover the safety profile.

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

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

The description is two concise sentences: the first front-loads the core action and outputs, the second provides usage rationale. No wasted words, and it is appropriately sized for the tool's simplicity.

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 no output schema, the description covers the action, scope, output fields, and use cases. This is sufficient for an agent to select and invoke the tool correctly without missing critical information.

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 only parameter (include_inactive) is fully described in the schema with a default value. The tool description does not add any additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields. This specific verb+resource+scope distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly states when to use the tool: to review monitoring before adding more subscriptions and to find an id to cancel. This implicitly contrasts with the subscribe and unsubscribe tools, providing clear 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?

The description goes far beyond the annotations by disclosing rate limits (5 per identifier per day), the claim_token return-and-lookup mechanism, the fact that it's free and outside the tool-call quota, and that the team reads digests daily. These are meaningful behavioral traits that the generic false hints in the annotations do not convey. No 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?

The description is long but every sentence earns its place, covering purpose, when/when-not, token mechanics, rate limits, and quota impact. It is front-loaded with the core purpose, then logically organized into usage conditions and behavioral details. It is not bloated; it is dense and purposeful.

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

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

Given no output schema, the description correctly explains the return claim_token and how to use it later. It also addresses prerequisites (account not needed), exclusions (other MCP servers), rate limits, and follow-up reading. The nested context structure is already in the schema, and the description completes the operational story.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable parameter-level guidance: message should be in terms of Pipeworx tools/packs and must not paste the user's prompt, and claim_token usage is illustrated with an exact example call. This richer semantics justifies a score above baseline, though the schema already covers the basic meaning of each parameter.

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

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

The description opens with a clear, specific verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact categories (bug, feature, data_gap, praise) and clearly distinguishes this tool from research/query siblings by framing it as feedback for the Pipeworx platform itself.

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

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

The description provides explicit when-to-use guidance for each category (bug, feature, data_gap, praise) and, crucially, explicit when-not-to-use guidance: it warns against filing feedback for tools from other MCP servers and directs the user to file with that server instead. It even clarifies how to identify Pipeworx tools, making the usage boundary unambiguous.

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 safety; description adds behavioral context about aggregation source, no PII, and caching behavior, plus the type of output data. This goes beyond 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?

Description is well-structured: a clear lead sentence, a bulleted list of use cases, and a final note on data source and caching. It is appropriately sized and 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 single-parameter, no-output-schema tool, the description covers input, output, and use cases sufficiently. It explains the output (pack, tool, count) and the window semantics, making it almost entirely self-contained.

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

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

The schema fully describes the window parameter with enum and guidance on 24h/7d/30d. The description restates the window options but adds no new semantic detail beyond the schema, so it meets baseline.

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

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

The description clearly states it returns trending tool usage from other agents, with specific output artifacts (top tools, top packs, total call volume). It distinguishes from sibling discovery tools by focusing on aggregate usage signal.

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 lists three explicit use cases for when to use the tool, such as discovering hot data sources or confirming a canonical tool. While it doesn't mention alternatives by name, the use cases provide clear situational 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 readOnly/idempotent annotations, the description discloses extensive behavioral details: monotonicity checks, partition-check threshold (>3pp), semantic similarity threshold (≥0.30 Jaccard), placeholder filtering (>20% returns null), and the fill-check logic with realizable_edge_pp ≤ 0 meaning 'do not trade it.' This gives the agent a deep understanding of what the tool does internally.

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 and dense, but its structure is logical: a one-line summary, then usage modes, then filters, then response shape. Each section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) is labeled and earns its place, though a more compact layout would improve scannability.

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 specifies the return structure (opportunities[] with fields, partition_check with fields, fill-check details). It also covers edge cases (placeholder filters, similarity thresholds, thin legs) and cross-references polymarket_fill_risk, making the tool self-sufficient for an agent.

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

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

Although the schema already describes both params (100% coverage), the description vastly expands their meaning: it explains the event slug format, that full URLs are accepted, the topic seed-question behavior, and the exact algorithms and responses each mode triggers. This goes far beyond the schema's basic type/description.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event vs topic) and a no-arg trending scan, and the detailed explanations of each mode separate it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to call with NO args, when to pass `event`, and when to pass `topic`, with recommendations ('event (recommended for a specific market)'). It also contrasts cross-event vs single-event catching patterns and directs to polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

The description goes far beyond the read-only/idempotent annotations by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, _diagnostics), the 24h-move warning, and model-specific traits (e.g., 'soft signal w/ halved Kelly', 'rare-by-design'). It also explains the rationale for excluding Fed bets and how knobs drop opportunities. This is rich, transparent behavioral disclosure that helps the agent understand what to expect.

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 excessively long and dense, including detailed model formulas, per-sport alpha values, and output field enumerations that could be conveyed in an output schema or supplementary docs. While it is structured with section headers and front-loaded purpose, many sentences are overly technical and repetitive (e.g., slippage details appear both in schema and description). It is not 'appropriately sized' and would benefit from trimming to concise high-level guidance.

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

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

Given the lack of an output schema and the complexity of this tool (9 parameters, multiple model families, nested response segments), the description is exceptionally complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the meaning of edge fields, the purpose of each knob, the filtering logic, and even the caching strategy. This provides a full mental model for the agent to invoke and interpret the tool correctly, leaving no major gaps.

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

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

Parameter schema coverage is 100%, so the schema already documents all 9 parameters with descriptions. The tool description adds some extra context around tradeable-edge knobs (min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable' and min_partition_leg_kelly's special handling of partitions), but most parameter meaning is already in the schema. This meets the baseline for high schema coverage, with only a slight incremental contribution.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and distinguishes itself from siblings by noting it discovers opportunities 'without paging hundreds of markets.' This clearly differentiates it from related tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description clearly frames when to use the tool (discovery of betting opportunities) and provides a wealth of configuration guidance via 'TRADEABLE-EDGE KNOBS' and diagnostics that explain why segments may be empty. It explicitly excludes Fed bets from ranking with a rationale, giving useful context. However, it never directly names alternative tools or states 'use this instead of X,' so it doesn't fully articulate when-not-to-use compared to siblings.

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

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

Annotations already mark it read-only, idempotent, open-world, and non-destructive. The description adds important behavioral context: snapshot gaps occur on cache-miss days, history is bounded by a 60-day TTL, and decay metrics use daily closes not intraday data. 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 dense but well-structured: a clear opening question, then Args, RESPONSE, and LIMITS. Every sentence adds useful detail, and the response format is explicitly enumerated, making it easy for an agent to parse.

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

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

There is no output schema, so the description fully explains the response shape (tracked, expired, snapshot_dates) and covers edge cases like snapshot gaps and TTL limits. It provides enough context for correct invocation and interpretation.

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 parameters are already well documented. The description repeats defaults and adds the concept of 'snapshot family' via the window argument, but does not meaningfully extend the schema's 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 gives a specific purpose: edge persistence and decay telemetry from daily snapshot data. It clearly distinguishes itself from the sibling polymarket_edges by focusing on time dynamics (how long has an edge existed, is it shrinking) rather than just current 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 clearly conveys when to use it: to compare fresh vs. aged edges and to understand whether an edge is decaying. It does not explicitly name alternative tools or state when not to use it, but the use case is well-defined and not misleading.

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

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

The description goes far beyond the annotations (which only indicate read-only/idempotent/safe) by detailing behavioral traits: it 'walks the ladder', returns specific metrics per leg in basket mode, identifies 'thin_legs[]' and 'forced_directional_risk', and warns about partial-fill dangers. This is exactly the type of behavioral context an agent needs and is not present in 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 long but every sentence earns its place. It is front-loaded with the core purpose, then cleanly structured into labeled SINGLE-MARKET and BASKET sections, followed by a clear usage directive. The use of capitalization for mode names aids scanning, and there is no filler 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?

Given the tool's complexity (two modes, many return fields, no output schema), this description is remarkably complete. It lists all returned fields for both modes, explains the size_usd semantics, and covers edge cases (thin books, partial fills, directional risk). It fully compensates for the absence of an output schema and leaves no significant gap.

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

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

Although the schema already has 100% coverage, the description adds significant interpretive meaning: for size_usd it clarifies 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains side defaults and mode selection (market vs event), enriching the schema's bare descriptions.

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

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

The description opens with a specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market and basket) and lists concrete outputs (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), making it unmistakably clear what the tool does and separating it from theoretical siblings 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 provides explicit when-to-use instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable; partial fills create unhedged positions), giving strong contextual guidance without needing to name all alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral details: the compatibility_warning logic with two distinct cases, temporal_alignment flag indicating when spreads are mathematically meaningless, and counters like skipped_cross_type/subtype that explain dropped comparisons. It also warns that real spreads are rarer than expected. This is substantial behavioral context that annotations 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 long but well-organized: purpose, modes, response structure, safety fields, and a final warning. Every sentence delivers substantive information, and the use of caps like 'TWO MODES' and 'SAFETY FIELDS' improves scannability. It could be slightly tightened, but the density is justified given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, matched spread with top_spreads_pp, compatibility_warning scenarios, and temporal_alignment. It covers edge cases (non-equivalent bet shapes, unrelated events) and explains the meaning of each safety field, making the tool fully usable without additional documentation.

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

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

The input schema already has 100% coverage with descriptions for all three parameters. The tool description adds value by explaining the two modes in detail, how 'topic' pre-maps to specific shortcuts, and how explicit parameters override the topic-mapped sides. This contextualizes the parameters beyond their individual definitions, though the schema already carries much of the load.

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 and precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings by focusing on cross-venue comparison and explicitly names two modes of operation, making the tool's scope unambiguous.

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

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

The description provides strong usage context: it explains the two modes ('topic' for pre-mapped shortcuts vs explicit tickers/slugs), when each is appropriate, and details cases where results are invalid (compatibility_warning conditions). It cautions that most pre-mapped topics are not tradeable, effectively telling the agent when to be skeptical. However, it does not explicitly name sibling alternatives, so it misses the highest bar for alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the tool's safety profile is clear. The description adds value by disclosing the return type ('Returns attribute rows (and geometry)') and clarifying the SQL-like semantics of the query parameters, which goes beyond 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 two sentences, front-loaded with the core verb, and every word earns its place. It succinctly states what it does, lists the key parameters, indicates the return type, and gives a practical sampling tip without redundancy.

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

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

For a query tool with 6 parameters, 1 required, and no output schema, the description covers the essential aspects: purpose, URL source, parameter list, return behavior, and a sample usage pattern. It positions the tool within the sibling workflow (search_datasets -> query_layer) and is fully sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. However, the description adds meaningful context by grouping the parameters into a coherent query pattern (SQL-like where, comma-separated out_fields, order_by, limit, offset) and offering a sample idiom for using them together. This exceeds 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 ('Query') and clearly identifies the resource (an ArcGIS Feature Service / Map Service layer) and the source of the URL (from search_datasets). This distinguishes it from sibling tools like search_datasets (finding datasets) and layer_info (layer metadata).

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

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

The description gives clear context: this tool is for querying a layer URL obtained from search_datasets, implying a workflow step. It also provides a practical usage tip ('Use where="1=1" + out_fields="*" to sample'). It stops short of explicitly contrasting with alternatives, but the reference to search_datasets and the tool's name effectively communicate when 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 declare readOnlyHint=true and idempotentHint=true. The description adds valuable context beyond these: the dual retrieve/list behavior and scoping to caller identity ('anonymous IP, BYO key hash, or account ID'). It does not contradict 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?

Four short sentences, each serving a distinct purpose: function, usage context, scoping, and related tools. No redundant or extraneous wording; the description is tightly packed with useful 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 tool with one optional parameter and no output schema, the description provides everything needed for correct invocation: what it does, when to use it, how to invoke it (with or without key), scoping, and relationship to sibling tools. The return semantics are implied by 'Retrieve a value' and 'list all saved keys'.

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 the single optional 'key' parameter with 100% description coverage, including the 'omit to list all keys' behavior. The description reinforces this and adds examples of typical key content (target ticker, address, research notes) but does not add new syntax or format details beyond the schema.

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

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

The description uses the specific verb 'Retrieve' and names the resource 'a value previously saved via remember', distinguishing it from sibling tools by referencing 'remember' and 'forget'. It also clarifies the optional list-all mode ('or list all saved keys'), making the purpose unmistakable.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier...' and provides complementary tools: 'Pair with remember to save, forget to delete.' It lacks an explicit when-not-to-use condition, but the guidance is clear enough for an agent to decide appropriately.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description goes beyond this by disclosing the mark_read side-effect, the payload fields, and the external feed URL. No contradiction; the read flag is a consumer cursor, not a mutation of the underlying alerts.

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 action, and each sentence adds value. No redundant phrasing or unnecessary detail.

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

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

Despite no output schema, the description explains what returned alerts carry, filtering options, mark_read behavior, polling suitability, and an alternative URL for external access. For a 5-optional-param tool, this is sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example filter type ("sec_8k"), clarifies "since" as ISO timestamp, and explains that mark_read affects subsequent calls. This adds meaning beyond the schema descriptions.

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

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

The description opens with "Pull fired events from your subscription feed," a specific verb+resource statement. It further details the return payload (source, citation_uri, raw event payload) and distinguishes itself from siblings like list_subscriptions or recent_changes by focusing on fired alerts on a persisted feed.

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 states "Polls work fine," giving clear polling context, and offers an alternative access method for scripts/dashboards (GET registry.pipeworx.io/alerts.json). However, it does not explicitly name sibling alternatives or when-not-to-use conditions, 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?

Beyond the annotations (read-only, idempotent), the description discloses a fan-out to multiple external APIs, a GDELT→GNews fallback on rate limits/5xx, and a soft-fail for USPTO due to PatentsView sunset. These behavioral details materially inform an agent's expectations and are not contradictory to the annotations.

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

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

The description is front-loaded with a concise statement of purpose, then a somewhat lengthy run of example queries, followed by structured details on sources, parameters, and return value. Each section earns its place, though the example list could be trimmed; still, it's not bloated or disorganized.

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

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

Given there is no output schema, the description compensates by describing the return format (changes[] grouped by source, total_changes, citation URIs). It covers data sources, fallback, and the key alternative. It omits specifics like empty-result behavior or pagination, but those are minor for this monitoring use case.

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% — every parameter has a thorough description. The tool description reiterates the `since` formats (ISO or relative) and the `value` examples (ticker or CIK) without adding new meaning. Baseline of 3 is appropriate because 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's purpose: a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It enumerates the exact sources (SEC EDGAR, GDELT/GNews, USPTO) and the return structure (changes[] grouped by source + total_changes count + citation URIs). It also distinguishes itself from entity_profile, leaving no ambiguity about scope.

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

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

The description provides explicit usage cues with natural-language examples ('What's new with X', 'updates on Acme') and gives a direct alternative: 'Use entity_profile instead when you want the static profile.' This clearly specifies when to use this tool versus the most relevant sibling.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false, but the description adds meaningful behavioral context beyond those flags: key-value storage, scoping by identifier, and persistence details (authenticated users get persistent memory; anonymous sessions retain for 24 hours). It does not explicitly describe overwrite behavior or return values, but the added scope/retention details justify a score above baseline.

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

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

The description is four sentences, each earning its place: the core action, usage triggers with examples, storage scope/retention, and pairing with related tools. It is front-loaded with the most important information and contains no filler, making it both concise and well-structured.

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

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

For a simple 2-parameter tool with no output schema and adequate annotations, the description covers all essential context: purpose, usage, persistence, scoping, and relationship to recall/forget. It also accounts for the user types (authenticated vs. anonymous), making it 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 description coverage is 100%: both 'key' and 'value' have informative descriptions, including examples for the key. The tool description reinforces the key-value structure ('Stored as a key-value pair') but does not add new parameter-level semantics beyond what the schema already provides. With high schema coverage, a baseline of 3 is appropriate, and the description's extra examples do not elevate it further.

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 specifies a clear action: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It identifies the resource (data/memory) and the scope, and it distinguishes from sibling tools by explicitly framing remember as the save operation while pairing with recall (retrieve) and forget (delete). This is a specific verb+resource+scope, well differentiated from 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?

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also names alternatives via 'Pair with recall to retrieve later, forget to delete,' making the boundaries between related tools clear. This exceeds simple context by offering both positive and negative usage direction.

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 valuable context beyond that: internal cascading through multiple lookup endpoints, auto-disambiguation of company names, and return of citation URIs. This gives the agent a clearer picture of what happens behind the scenes.

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 slightly long but well-organized, starting with illustrative examples, then a clear mission statement, and then structured type-by-type details. Every sentence contributes information; no filler. It might be trimmed slightly, but the structure aids readability.

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

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

Without an output schema, the description takes on the burden of explaining return values, and it does so clearly for both entity types (including citation URI). It also covers disambiguation and internal cascading. It could mention error handling or lack of results, but for an ID-resolution tool this is sufficiently complete.

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

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

Schema coverage is 100%, but the description exceeds it by explicitly clarifying value formats (ticker, CIK, or name for company; brand or generic for drug), giving concrete examples, and stating what each type returns. This is genuinely additive and leaves no ambiguity about how to fill the parameters.

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 ('resolve') with a clear resource ('entity') and states the exact function: mapping user-spoken names to canonical identifiers. It distinguishes itself from sibling tools by emphasizing it's the first stop when you need an ID, and it lists supported entity types with return values, making its scope 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?

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), which is strong. However, it does not mention any alternative tools or when to prefer them, nor does it state when not to use the tool. That small gap prevents a perfect score.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 three sentences, front-loaded with the core purpose, and each sentence adds value: purpose, method, and output. The example quote is illustrative without being verbose. No wasted words.

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

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

Given 4 params and no output schema, the description adequately covers the return shape (ranked list with score, confidence, signal density) and the core use case. It does not explain the models or _apiKey parameters, but the schema handles those. Missing some nuance like what 'signal density' means, but acceptable for 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add parameter-level details beyond what the schema provides, though it reinforces the 'brand + competitors' framing in the schema. This meets the baseline for full schema coverage.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from the sibling ai_visibility_check by stating it probes each entity and ranks results, and from compare_entities by focusing on AI visibility. The purpose is unmistakable.

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

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

It gives clear context: 'Useful for competitive AI-marketing audits' and an example query, showing when to use. It implies this is for side-by-side comparison rather than single checks, but does not explicitly name alternatives or exclusions (e.g., when to use compare_entities instead).

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

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

Annotations declare readOnlyHint/idempotentHint, and the description adds meaningful behavior beyond that: composite fan-out, bundlephobia's first measurement latency (5-30s), graceful degradation with sources_failed, and the list of returned fields. 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 dense and front-loaded with the purpose, then lists output fields, ecosystem scope, and caveats in a compact, scannable format. Every sentence contributes essential information without fluff.

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

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

This is a complex composite tool with no output schema, so the description carries the burden of explaining return values, failure modes, latency, and ecosystem limitations. It does so thoroughly, including listing summary fields, links, and alternative behavior for non-NPM ecosystems.

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

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

Schema coverage is 100% and both parameters (package, version) have clear descriptions. The tool description does not add significant parameter-level context beyond the schema, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'should I add this npm package to my project' check, explicitly enumerating the data sources (deps.dev, bundlephobia) and the exact output block. It distinguishes from siblings by noting NPM-only scope and directing other ecosystems to deps.dev directly.

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 ('Use whenever an agent asks is X safe / popular / small') and when-not-to-use ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also sets expectations for partial failures and timeouts.

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, covering safety. The description adds meaningful behavioral detail: it returns specific fields (name, summary, record_count, owner/org, url) and references the City of Richmond scope, which is helpful given there is no output schema.

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 with no superfluous content: the first sentence states the action and scope, the second lists return fields and adjacent tools. It is front-loaded and every clause contributes to understanding.

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

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

The tool is simple, and the schema fully documents parameters while annotations cover the safety profile. The description explains return values and gives a workflow hint, but it does not mention behavior when query is omitted or org_id is customized. Given schema already describes these parameters, the missing context is minor.

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 description covers 100% of parameters with explicit descriptions for query, limit, and org_id. The tool description adds no extra parameter-level meaning beyond the keyword-search mention, so 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 tool's purpose: searching City of Richmond GIS open geospatial datasets by keyword, with concrete examples of dataset types and a specific list of returned fields. It also distinguishes itself from siblings by mentioning the follow-up tools query_layer/layer_info, making the resource and action unambiguous.

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

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

The description implies a clear workflow: use this tool to discover datasets, then pass the returned Feature Service URL to query_layer/layer_info. It does not explicitly list alternative search tools or state when not to use it, but the workflow guidance provides practical usage context.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and that output includes offsets for verification. These reveal operational behavior not captured by annotations.

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

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

Four sentences, front-loaded with the core purpose, then expanding to use cases, pairing, and technical details. Every sentence contributes new information without redundancy, making it dense yet efficient.

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

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

Given no output schema, the description compensates by describing the return format (passages with offsets and scores), constraints (200K cap), and integration with ask_pipeworx_grounded. It covers what an agent needs to decide when to use the tool and interpret results, making it highly 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 description coverage is 100%, and the field descriptions already explain text, limit, and query. The tool description adds examples (SEC 10-K, article) and context about 'already pulled' text, but this is incremental rather than substantive, so the baseline of 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', using a specific verb and resource that clearly differentiates this tool from siblings like ask_pipeworx. It details inputs (text + natural-language query) and outputs (passages with offsets and scores), 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 explicitly states 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, naming the alternative and how to combine them. This gives clear when-and-alternative guidance that goes beyond generic context.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: returns new subscription id, requires OAuth, SMS phone verification, 10/day cap, webhook auto-disabled after 10 consecutive failures, and webhook signing secret returned only once. This goes beyond the annotations. However, it does not mention idempotency or what happens on duplicate subscriptions (e.g., whether duplicates are allowed or deduplicated), which is relevant given the idempotentHint.

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

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

The description is appropriately detailed for a complex tool with multiple subscription types and delivery channels. Information is front-loaded with the core purpose, then organized logically by type and channel. Though long, each sentence earns its place; minor redundancy exists between the main description and delivery schema, but the description consolidates critical details for agent use.

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

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

Given the tool's complexity (3 params, nested objects, 5 enums, no output schema), the description is quite complete. It covers supported types, params examples, delivery options, prerequisites, and pitfalls. The only notable gap is the absence of explicit return-value format beyond 'new subscription id' — though without an output schema, more detail on the response structure would help. Still, it is strong overall.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning by providing concrete examples for each type (e.g., items:["5.02"] = officer change, params:{topic:"fed"}, series_id:"UNRATE"), and elaborates delivery channel semantics (email templated alert, SMS verified phone, webhook HMAC signing). It substantially exceeds the schema's brief descriptions, justifying 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 starts with a specific verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and explicitly lists supported types and delivery channels. It clearly distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe', which handle different lifecycle operations.

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 on when to use (creating monitoring subscriptions) and prerequisites (requires Pipeworx OAuth account; anonymous + BYO cannot persist). It implicitly excludes alternatives by covering subscription creation, and even notes delivery limitations (10/day SMS cap, verified phone). However, it does not explicitly name sibling tools as alternatives for listing/removing 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 readOnly, openWorld, and idempotent behavior, and the description adds valuable context: it returns category-bucketed examples, includes tool+argument shapes, reads from a live catalog of thousands of tools, and works with zero arguments or a focused topic. 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 front-loaded with user phrasings, then provides purpose, output format, usage instructions, and when-to-use guidance. Every sentence contributes value, though the initial list of alternative queries makes it slightly verbose. Structured well for an agent to parse.

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

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

For a simple one-parameter tool with no output schema, the description adequately explains what it returns, how to call it with/without arguments, and when to use it. The call patterns and typical use cases are fully covered, making it complete for an agent to select and invoke correctly.

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

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

The schema already provides 100% coverage for the 'topic' parameter, including the allowed values and the effect of omitting it. The description's examples ('finance', 'pharma', 'betting') and 'to focus' wording largely repeat the schema, adding minimal new semantic meaning beyond the structured field.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses specific verbs like 'Returns' and positions itself distinctly from siblings by naming meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It also clarifies the optional 'topic' parameter for focusing, and implies alternatives (ask_pipeworx, compare_entities, etc.) for more specific tasks.

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 (which already indicate non-destructive, idempotent write), the description discloses critical behavioral details: ownership is enforced, and the row is deactivated rather than deleted, preserving historical events via recent_alerts. This adds significant value.

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 primary action, and includes essential caveats (ownership, deactivation) without redundancy. Every sentence earns its place.

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

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

For a simple single-parameter tool with no output schema, the description is complete. It covers purpose, ownership, and the non-destructive nature, providing enough context for the agent to use the tool correctly and understand downstream effects.

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

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

Schema coverage is 100% for the single parameter 'id', and the schema description already explains it as the subscription uuid from subscribe. The tool description adds no additional parameter semantics beyond what the schema provides, so 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 clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource. However, it does not explicitly distinguish from sibling tools like subscribe or list_subscriptions, though the action is obvious. The ownership enforcement adds scope clarity.

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

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

The description provides clear context on when to use the tool: canceling a subscription by id, with ownership constraints. It does not explicitly mention alternatives or exclusions, but the context is sufficient for a focused action.

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/open-world/idempotent annotations, the description discloses the dual-path behavior (SEC EDGAR/XBRL fast path vs. grounded fallback), the 'exact percent-delta math,' and the output contract (verdict, actual value with pipeworx:// citation, reasoning). It also mentions verbatim evidence and automatic routing, which are useful behavioral traits.

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

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

The description is information-dense but front-loaded with natural-language examples and then effectively explains use case, routing, and output. It is somewhat long but every sentence contributes value; the structure is organized with a semicolon and em-dash for readability.

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?

As there is no output schema, the description explicitly enumerates the return values: verdict types, actual value with citation, and reasoning. It also explains when each routing path applies and gives example claims, making the tool's behavior largely self-contained despite its complexity.

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

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

The input schema already provides complete descriptions for both parameters (claim and tolerance_pct), so the baseline is 3. The description adds minimal parameter-specific detail—only implying the tolerance idea via 'exact percent-delta math'—so it does not significantly enhance schema 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 is highly specific: 'natural-language claim verification against authoritative sources' with explicit trigger phrases and output verdicts. It clearly distinguishes the tool from siblings by focusing on fact-checking a user's claim, not generic Q&A or research.

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

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

The description gives an explicit 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates two routing cases (company-financial claims vs. other claims) and states it replaces 4–6 sequential calls, but it does not name specific alternative tools or provide when-not-to-use exclusions.

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