Arcgis Brampton

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable transparency about cost implications (free default vs. BYO Anthropic key), model default (Workers AI Llama-3.3-70b), and the return structure, going 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 concise (three sentences), front-loaded with the core purpose, and each sentence earns its place: what it does, model/cost details, return format, and use cases. No wasted words.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description provides a complete picture: it explains the return format (per-model {score, confidence, signals, raw_response} + combined view), notes cost behavior, and gives usage context. Annotations cover safety, so nothing critical 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 the baseline is 3. The description adds meaning beyond the schema by specifying the default model name and clarifying that passing `_apiKey` is required for Anthropic probing, which supplements the schema's parameter docs.

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 specifies the action ('probe one or more LLMs'), the resource (LLMs), and the output (visibility score 0-100 per model). It is distinct from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on scoring model knowledge rather than Q&A or competitor scanning.

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 states clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), indicating when to use the tool. It does not explicitly mention alternatives, but the context is clear enough for an agent to select it 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which cover safety and idempotency. The description adds behavioral context: it routes questions to appropriate tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. The only minor gap is not detailing rate limits or concurrency limits.

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

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

The description is lengthy but well-structured, starting with the core directive (prefer over web search) and then expanding with examples and sibling distinctions. It wastes little space, though it could be slightly tighter without losing clarity.

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

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

Given no output schema, the description successfully explains what the tool returns (structured answer with citation URIs). Combined with annotations for safety and idempotency, and clear usage guidelines relative to 33 siblings, the description is complete for a complex routing tool. The agent has everything it needs to decide when and how to invoke it.

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

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

Schema description coverage is 100% (all 6 parameters described as aliases for 'question' in natural language). The description adds value by explaining that the input is a question/request, but doesn't elaborate on formatting, constraints, or what constitutes a good question. Baseline 3 is appropriate since the schema fully documents 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 explicitly states it handles factual questions about structured/authoritative data (SEC filings, FDA, FRED, etc.) and routes to 5,563 tools across 1,462 sources. It clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research by stating when to use each, making the purpose 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?

The description provides explicit when-to-use guidance (prefer over web search, default entry point), when-not-to-use (step up to ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions), and lists example queries. It even covers breaking news routing.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: it is a beta with candidate routing improvements, currently matching the stable router, and it is a full working router (not a fallback). It also explains the comparison process for deciding merges, which is beyond the annotations.

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

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

The description is a single paragraph of four sentences, front-loading the main purpose and beta nature. Every sentence adds value: identity, current state, usage instruction, and clarification. No wasted words.

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

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

Given the complexity (beta of a large router) and lack of output schema, the description covers the essential points: experimental nature, identical to stable currently, usage guidance, and comparison purpose. It does not describe the output shape, but it states 'same response shape' as ask_pipeworx, which is sufficient if the agent knows that tool. Could be more explicit about what happens when a candidate is active, but still complete enough.

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

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

Schema coverage is 100%, with all six parameters (all aliases for 'question') documented. The description does not mention parameters or add any additional semantics beyond the schema. 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 is a beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental routing improvements and current state (no active candidate, so identical to stable). The verb 'ask' and resource 'pipeworx' are 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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives clear when-to-use guidance. It does not explicitly list when not to use it, but the context implies it is for experimental routing rather than stable production use.

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

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

The description adds significant behavioral context beyond the annotations. It explains the internal routing process, the strict extraction policy ('ONLY what the tool result contains'), details the success return format (answer, evidence, confidence, source, fetched_at, refusal_reason:null), and lists all possible refusal reasons. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is concise (~120 words) and well-structured: purpose statement first, then routing/behavior, then return format, then usage guidelines. Every sentence adds value, with no redundancy or filler.

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

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

For a complex tool with internal routing, refusal reasons, and extra cost, the description is complete. It explains the return format (since no output schema), the refusal reasons, the trade-off vs ask_pipeworx, and the appropriate use cases. The evidence field is described as 'verbatim quote', which is sufficient. All critical aspects are covered.

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

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

Schema description coverage is 100% (all aliases explained). The description adds only the context of 'high-stakes' to the question parameter, but does not provide additional syntax, format, or constraints beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the verb (extracts answer using only tool result), the resource (the same routing as ask_pipeworx), and distinguishes it from siblings by emphasizing grounding and refusal behavior. The first sentence immediately conveys the core purpose.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also states when to prefer the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is explicit and actionable.

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

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

The description is exceptionally transparent about runtime behavior, far beyond the annotations. It discloses the fan-out mechanism, low-confidence short-circuit behavior, closed-market handling, illiquid spreads, fallback logic for news sources (GDELT 429s retry), and resolution-rule risk with a concrete warning about flat-50¢ void settlements. This adds significant context beyond readOnlyHint/openWorldHint/idempotentHint and does not contradict any annotation.

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

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

The description is long but well-structured with bolded sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that make it scannable. Each section adds unique value, and the main purpose is front-loaded in the first sentence. It omits fluff; every sentence contributes to understanding the tool's complex behavior. Slightly verbose, but appropriate 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?

Despite having no output schema, the description fully specifies the response shape (result.market, result.analysis, result.evidence, parent_event, statuses) and important edge cases (low-confidence, closed markets, wide spreads, cancellation rules). It covers error/fallback behaviors and provides examples of fan-out, making the tool's behavior understandable end-to-end. This is a complete description for a complex research tool.

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

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

The schema covers all 3 parameters with descriptions, so the baseline is 3. The description adds minimal parameter-level detail beyond the schema: it reiterates the market parameter's accepted formats (slug/URL/question text) and mentions 'quick vs thorough' fan-out indirectly via examples, but it does not explain depth or include_raw beyond what the schema already states. No gaps, but no added value either.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from siblings like polymarket_edges or validate_claim. The verb 'research' plus the resource 'Polymarket bet' and the outcome 'evidence packet + market-vs-model comparison' make the purpose explicit.

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

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

The description provides clear usage context with the 'Use for' line, which guides when to invoke the tool. However, it does not explicitly state when NOT to use it or name alternative tools for other situations. It gives strong contextual signals (e.g., what types of bets it handles) but stops short of a full when/when-not comparison with 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, adverse-event counts), sorting behavior, and output format (paired data + pipeworx:// citation URIs). It even notes efficiency ('Replaces 8–15 sequential lookups'). 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 information-dense but remains relevant and efficiently phrased. It front-loads example queries and core purpose, then adds specifics. Slightly longer than ideal, but every clause contributes value, so it earns a high score.

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

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

Given no output schema, the description fully compensates by explaining the return data (paired data, citations), sorting logic, and entity-specific attributes. It also anchors usage within the tool ecosystem by referencing alternatives. This is a comprehensive description for a 2-parameter 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?

Even though the schema covers 100% of parameters, the description adds significant meaning: it defines what type='company' retrieves (latest 10-K financials) versus type='drug' (FAERS, FDA, trial counts), and provides concrete examples for values (tickers/CIKs, drug names). This goes well beyond the schema's minimal descriptions and aids correct invocation.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It gives specific example user phrasings ('Compare X and Y', 'which is bigger') and distinguishes from sequential single-pack lookups, making the purpose unmistakable and differentiating 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?

Explicit usage guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use company vs drug types and mentions off-calendar fiscal year handling, giving clear context for both selection and expected behavior.

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

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

The description discloses many behavioral traits beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains the decomposition into facets, parallel routing, return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), timing (15-60s, up to ~90s), semantic excerpting, hop field, and iteration behavior. 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 lengthy but every sentence provides necessary information. It front-loads critical prerequisites (account requirement, alternative) and then details behavior. It could be more structured (e.g., bullet points), but it is not repetitive or vague. The verbosity is justified by the complexity of the tool.

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

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

Given the complexity (2 parameters, no output schema, many behavioral details), the description is remarkably complete. It covers account prerequisites, timing, output structure, limitations, iteration behavior, and even caveats about when results may be empty. There is no missing information that would prevent an agent from using the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the depth levels in context (number of facets, gap recovery, contradictions) and providing example questions. It also clarifies that 'standard' is default and that the question can be broad/multi-part. This enriches the 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 clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in a single call. It distinguishes itself from siblings like ask_pipeworx by specifying that this is not open-web search and is meant for broad/multi-part questions over structured data. The verb 'research' and resource 'structured data sources' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also notes the account requirement and that depth:'thorough' needs a paid plan. This gives clear context for 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?

With annotations already declaring read-only, idempotent, non-destructive behavior, the description adds valuable context: it returns top-N relevant tools with names, descriptions, and full input schemas ready to call, eliminating second lookups. It also notes it should be called first, but doesn't describe internal behavior like ranking methodology or edge cases. This is solid added value beyond annotations.

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

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

The description is appropriately sized, front-loaded with the core purpose, and uses a domain list to convey scope. Every sentence contributes value, though the domain enumeration is lengthy. Slightly more concise phrasing could be possible, but it's well-structured.

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

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

Given the tool's complexity and lack of an output schema, the description does a good job explaining return values (top-N tools with names, descriptions, schemas) and when to use it. It doesn't mention error cases or no-match behavior, but those are less critical for a discovery tool. Overall it's complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100% with detailed descriptions for query and includes aliases and examples. The description itself doesn't add parameter-level meaning beyond the schema, but the schema comprehensively documents all six parameters, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Find tools' with a clear resource ('tools') and explains the function as browsing, searching, or discovering tools for a list of data domains. It distinguishes itself from siblings by instructing to call it FIRST for option discovery, unlike task-specific tools like search_datasets or validate_claim.

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 when you need to browse, search, look up, or discover...' and 'Call this FIRST when you have many tools available' which clearly guides usage. However, it does not explicitly mention when not to use or name alternative tools, just implies the discovery scenario, so not a perfect 5.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by revealing internal behavior: it fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF in 'ONE parallel call.' It also discloses the USPTO PatentsView API sunset and soft-fail behavior, the GDELT→GNews fallback, and the exact structure of returned fields. This contextual richness is exactly what agents need.

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

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

The description is long but every sentence contributes: example queries, preference guidance, return field breakdown, source notes, and parameter constraints. It is front-loaded with user intent examples and ends with the parameter caveat. No wasted phrases; the density is justified by 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 full responsibility for explaining returns. It enumerates each returned component: cik + company_name, recent_filings (with URIs), fundamentals (with sort order), patents, news, and LEI. It also covers known limitations and fallbacks, making the description complete for a complex multi-source tool.

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

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

The input schema already describes both parameters fully (type enum with only 'company', value with ticker/CIK guidance and 'use resolve_entity first'). With 100% schema coverage, the baseline is 3. The description reinforces this with concrete examples ('AAPL', '0000320193') but does not add meaning beyond what the schema already provides, so a 3 is appropriate.

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

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

The description opens with concrete trigger phrases and clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes the tool from sibling resolve_entity by explicitly noting that names are not supported and from chaining single-pack SEC/XBRL/news lookups by advising 'ALWAYS PREFER over chaining.' This makes the purpose and 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?

The description provides extensive guidance on when to use the tool: 'Tell me about X', 'research Acme', 'brief me on Tesla', 'company profile for Microsoft', etc. It also gives exclusions: 'names not supported (use resolve_entity first if you only have a name).' It even explains the patent soft-fail scenario and news fallback behavior, giving agents clear conditional use guidance.

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

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

The description's core action ('Delete') aligns with the annotations destructiveHint=true and idempotentHint=true. It does not contradict them. However, it adds little behavioral detail beyond what the annotations already disclose—it does not explain what happens if the key doesn't exist, whether deletion is permanent, or any side effects. Since annotations cover the safety profile, the description's marginal contribution is limited.

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

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

Two concise sentences: the first states the action and target, the second gives usage guidance and complementary tools. No filler, no redundancy.

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

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

For a simple one-parameter delete tool with full schema and annotations, the description is sufficient. It provides usage context (when to delete) and pairing advice. The lack of an output schema is acceptable because the operation is straightforward, though the description does not state what happens after deletion (e.g., confirmation or error handling), which would make it truly complete.

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

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

The input schema has complete coverage (100%) for the only parameter `key`. The description merely states 'by key' without additional meaning. With full schema coverage, the baseline is 3; it adds no further semantic detail.

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 ('Delete') and a clear resource ('previously stored memory') and explicitly states the operation is by 'key'. This directly distinguishes the tool from siblings like remember and recall, which are mentioned for context.

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 ('context is stale', 'task is done', 'clear sensitive data') and mentions alternative/complementary tools ('Pair with remember and recall'). This gives concrete usage guidance beyond what the schema provides.

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

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

The annotations already mark it as readOnly and idempotent, but the description adds valuable behavioral context beyond that: it fetches the URL, extracts key content, and emits a standard markdown blob. It also states the output is 'a single text blob ready to drop at site-root/llms.txt,' giving the agent a clear expectation of the result. No contradiction with annotations.

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

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

The description is concise and well-structured: a clear first sentence, a breakdown of the process and output, and a short list of use cases. Every sentence adds value without redundancy, and it front-loads the purpose.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is remarkably complete. It covers input (any URL), process, output format, and use cases. The lack of an output schema is mitigated by the explicit description of the output as markdown text.

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

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

Schema coverage is 100%, with both parameters ('url' and 'max_links') clearly described in the schema. The description does not add additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's verb+resource: 'Generate a production-ready llms.txt file for any URL.' It specifies the process (fetches, extracts, emits) and distinguishes itself from sibling tools by focusing on the specific llms.txt format and purpose (AI crawler indexing). This is unambiguous and unique.

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 with 'Useful for:' scenarios, covering client work, personal projects, and competitor auditing. However, it does not explicitly state when not to use this tool or mention alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about what data is returned (fields, geometry, record count, capabilities), but does not disclose potential error behavior, URL validation, or rate limits. This is a moderate value-add beyond the annotations, consistent with a 3.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then efficiently lists the return types. Every word earns its place; there is no fluff or redundancy.

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

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

With one parameter, strong annotations, and no output schema, the description carries the burden of explaining what the agent will get. It does so by enumerating fields, geometry type, record count, and capabilities, which is sufficient for deciding to call the tool. However, it omits details like response structure or error handling, so it is not fully exhaustive—just short of a 5.

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 fully documents the single 'url' parameter with a description and an example, giving 100% coverage. The tool description repeats the idea of 'by url' but adds no new meaning about the parameter format, constraints, or behavior. With high schema coverage, the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and identifies a precise resource ('an ArcGIS Feature/Map Service layer's schema by url'), then lists the concrete data returned: fields, geometry type, record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer, which would query data rather than 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 provides clear context: this tool is for retrieving schema/metadata from a layer URL. It does not explicitly name alternatives or exclusions (e.g., 'use query_layer to fetch features'), but the purpose is specific enough that an agent can infer when to use it. Since no when-not guidance is given, it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing the exact return fields and clarifying that it lists 'active' subscriptions by default, complementing the include_inactive parameter without contradicting annotations.

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

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

The description is two sentences: the first states the purpose and return fields, the second gives usage guidance. It is front-loaded, concise, and every sentence adds value with no repetition or 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?

For a simple list tool with one optional parameter and no output schema, the description is complete. It states the scope ('caller's active subscriptions'), lists the return fields, and provides usage guidance. The rich annotations cover the safety profile, so no additional behavioral disclosure is needed.

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

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

The input schema fully describes the include_inactive parameter with a clear description, achieving 100% schema coverage. The tool description does not add parameter-specific semantics beyond that, 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 'List the caller's active subscriptions' with a specific verb and resource, and lists the return fields. This distinguishes it from sibling tools like subscribe and unsubscribe, which are for creating or removing subscriptions.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call it. It doesn't explicitly name alternatives, but the intended use is clear.

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

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

Annotations are all false, so the description carries the full transparency burden. It discloses rate limiting (5 per identifier per day), quota exemption, token-based follow-up without an account, daily digest reading, and scope constraints. There is 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 purpose is front-loaded in the first sentence and the description is well organized, but it is fairly long. Most sentences earn their place, though the roadmap/digest motivation is useful context rather than selection-critical 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?

With four parameters, no required fields, a nested context object, and no output schema, the description covers everything an agent needs: return token behavior, rate limits, scope boundaries, and follow-up semantics. It is complete and 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?

Schema coverage is 100%, but the description adds meaningful workflow context: it explains what type categories mean in prose, gives message content guidance, and fully explains the claim_token param's round-trip behavior. The context object details are left to the schema, which is acceptable given high coverage.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool as a feedback channel and distinguishes it from sibling tools by explicitly limiting scope to tools served by this Pipeworx connection.

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

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

The description gives explicit when-to-use categories (bug, feature/data_gap, praise), an explicit when-not-to-use case (tools from other MCP servers), and practical guidance such as not pasting end-user prompts. It also explains the claim_token follow-up workflow for reading resolution status.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds meaningful context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This gives the agent a clear picture of freshness and reliability.

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, zero wasted words; the 'Useful for' list is compact and actionable. Information is front-loaded with the core function first.

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 single optional parameter and the absence of an output schema, the description is complete: it states what is returned (top tools/packs/count), the data philosophy, and caching. It covers return value structure sufficiently with '(pack, tool, count)'.

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

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

Schema describes the 'window' parameter with its default and trade-offs, and the description merely repeats the enum values. Since schema covers the parameter fully, description adds no additional semantic value.

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

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

The description clearly identifies the tool as returning trending tool/pack/call-volume data on Pipeworx, with a specific verb ('Returns') and resource ('top tools, top packs, total call volume'). It distinguishes itself from discovery tools by emphasizing it's specifically 'what other AI agents are calling on Pipeworx right now.'

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?

Lists three explicit use cases (hot data sources, confirming canonical tool, checking alignment) that tell an agent when to invoke it. Does not explicitly name alternatives or exclusion criteria, but the use-case framing is strong enough to guide 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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description discloses detailed behavioral traits: how event mode walks child markets, the threshold for partition deviations (>3pp), the Jaccard similarity anchor (≥0.30), placeholder filtering rules, and the fill-check mechanics with realizable_edge_pp. These enrich the agent's understanding without contradicting 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 core purpose, but it is a single long paragraph. While every sentence earns its place, the sheer length and lack of visual segmentation (e.g., bullet points) slightly reduce scannability. Still, it is efficiently worded and appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description compensates by explaining the response structure ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)') and the fill_check output, along with edge-case behaviors (e.g., null arb signal for >20% placeholders). The coverage of both modes, filters, and risk checks makes it fully contextually 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?

Although schema coverage is 100%, the description adds significant meaning beyond the schema: it explains the no-args behavior, contrasts event vs topic modes in depth (e.g., 'walks child markets, checks date-axis / threshold-axis ordering'), and clarifies how the topic mode 'searches related events across the platform, flattens markets, runs the comparator on the union.' This goes far beyond the basic schema descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges or polymarket_fill_risk, which focus on different aspects of Polymarket analysis.

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

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

The description provides explicit mode instructions ('Call with NO args for a trending_scan', 'pass `event` for the strongest per-event partition_check', 'or `topic` for a themed cross-event scan') and names an alternative tool ('For custom sizing use polymarket_fill_risk'). It also warns when not to trade ('do not trade it'), offering clear decision 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 (readOnlyHint=true, idempotentHint=true, etc.) by disclosing internal behaviors: caching at KV level for 1h, response structure with diagnostics (`_diagnostics`), filtering rules (partition_overround placeholder threshold), Kelly caps (0.25), slippage handling, and the 24h-move warning. It also explains why Fed bets are excluded, giving the agent deep insight into tool behavior.

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

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

The description is extremely long and dense, covering model families, response segments, filter knobs, and diagnostics in a single block. It is well-organized with capitalized section headers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL), but it could be more concise. Every sentence adds information, yet the sheer length makes it less scannable than ideal.

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

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

Despite having no output schema, the description meticulously documents the response structure, including top-level keys (`by_segment`, `fed_candidates`, `_diagnostics`) and nested contents. It also explains caching, error handling (visible via diagnostics), and edge cases (placeholder filters, rare-by-design concentrated longshots). This provides a complete mental model for the agent.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by explaining the rationale and interplay of knobs (e.g., 'min_kelly never filters them' for partition arbs, and 'Tradeable-edge knobs drop opportunities where edge isn't realizable'). This contextualizes parameters beyond their individual schema descriptions, earning a 4.

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

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

The description opens with a clear, specific statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further states it's 'Built for "what should I bet on today"', unambiguously distinguishing this from siblings like polymarket_arbitrage or polymarket_edge_tracker by its focus on proprietary Pipeworx data disagreement discovery.

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

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

The description provides clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and mentions exclusions from ranking (Fed bets). However, it does not explicitly name alternative tools or state 'use this instead of X', so it falls short of a full 5.

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

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

Even with annotations indicating read-only/idempotent safety, the description goes far beyond with rich behavioral detail: response structure (tracked/expired/snapshot_dates), signed edge values, trend categories, decay calculation basis, TTL limits, and snapshot gap behavior. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then uses Args/RESPONSE/LIMITS labels to structure the information coherently without wasting 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?

For a tool with only 2 params and no output schema, the description fully compensates by explaining the response object in detail, data limitations, TTL boundaries, calculation basis, and what gaps in snapshot dates mean. This is a complete mental model for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical nuance: days is a 'lookback', window is a 'snapshot family', and it clarifies defaults (14, '1wk') and maximum (30), which gives the agent better intuition than the raw schema alone.

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

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

The description clearly states a specific verb and resource: 'Edge persistence and decay telemetry' answering a concrete question. It distinguishes from the sibling 'polymarket_edges' by focusing on time-series persistence, making the purpose unambiguous.

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

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

Provides clear context for when to use: when you need to know how long an edge has existed and whether it's shrinking. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the walk-the-ladder behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), basket-mode aggregation (theoretical_sum vs realizable_sum), and risk indicators (thin_legs, forced_directional_risk). It also explains default auto-side logic. No annotation contradiction exists.

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

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

The description is long but tightly structured using labeled SINGLE-MARKET and BASKET sections. Each sentence provides operational detail (parameters, return values, risks) without redundancy or filler. The front-loaded first sentence immediately establishes the tool's core function.

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 returns and does so comprehensively: it enumerates single-market outputs and basket outputs, describes verdict categories, provides numerical defaults and clamps, and warns about the primary risk scenario. Complexity is high, yet the description fully covers actionable usage.

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

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

Although the input schema covers all four parameters, the description adds critical semantics: it differentiates size_usd meaning between single-market ('max spend on buys, target proceeds on sells') and basket ('settlement notional S — shares per leg'), clarifies side options per mode, and explains the default auto behavior for basket side selection.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly differentiates from sibling tools by focusing on fill-risk validation and clearly delineates single-market and basket modes, making the tool's purpose unmistakable.

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

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

Directive usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial fills converting arb into unhedged directional position), offering clear when-to-use and why-not-to-skip context.

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

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

The description goes far beyond the readOnly/idempotent hints by detailing safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type counters. It explains when spreads are meaningless and why the tool may return warnings, giving the agent deep understanding of edge cases. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). The main purpose is front-loaded. Some redundancy exists (e.g., pre-mapped ≠ tradeable is stated twice), but most sentences earn their place by explaining complex safety behaviors.

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 thoroughly explains return values: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers parameter usage and caveats, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context by explaining the two parameter modes (pre-mapped topic vs explicit override) and listing the 10 topic shortcuts. This helps the agent understand how the parameters interact, exceeding the schema descriptions alone.

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

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

The description opens with a specific verb+resource: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on spread across the two venues and explicitly stating the purpose. It also explains the core concept of price differences between venues.

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 on how to use the tool with two modes (topic shortcuts vs explicit pairing) and cautions that pre-mapped topics often produce compatibility warnings. However, it does not explicitly state when to use this tool instead of alternatives, nor does it list excluded scenarios beyond non-equivalent bet shapes.

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

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

With strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds meaningful behavioral context beyond annotations. It discloses the return type: 'Returns attribute rows (and geometry)', and clarifies the query syntax. It also goes beyond schema by providing an example usage pattern for sampling, which is valuable for an agent to understand expected behavior.

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

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

The description is three sentences long, front-loaded with the primary action, and each sentence provides distinct useful information: the core query operation, the parameter categories, and a sampling tip. There is no redundancy or filler; it is appropriately sized 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?

Given the tool has no output schema, the description sufficiently covers return values ('attribute rows and geometry'). It enumerates all parameters, references the source of the url (search_datasets), and provides a usage example. The description is complete for an agent to understand the tool's purpose, inputs, and outputs without missing critical context.

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

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

While the schema covers 100% of parameters, the description adds semantic meaning by highlighting the SQL-like nature of 'where' and the comma-separated format of 'out_fields'. It also suggests a specific combination ('where=1=1' and 'out_fields=*') to sample data, providing practical guidance that the schema alone does not convey. This exceeds the baseline for fully documented 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 clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. The verb 'query' and resource 'layer' are specific, and the mention of SQL-like parameters and return of attribute rows distinctively identifies this as a data retrieval tool. It also distinguishes itself from siblings like layer_info (metadata) by focusing on querying features and returning geometry.

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

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

The description provides clear usage context by specifying the url comes from search_datasets, and gives a practical sampling tip: 'Use where="1=1" + out_fields="*" to sample.' This implies when to use the tool (after finding a dataset) and how to use it effectively. However, it does not explicitly mention alternatives or when not to use it, leaving some room for ambiguity with sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of retrieving vs listing all keys, which is useful 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 three sentences, front-loaded with the core action, and each sentence adds value: functionality, use cases, and scoping/pairing. No fluff or repetition.

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

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

For a simple one-parameter read-only tool with strong annotations and no output schema, the description fully covers purpose, usage context, scoping, and relationship to sibling tools. Nothing significant is missing.

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

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

Schema coverage is 100% and the property description already explains the key parameter ('Memory key to retrieve (omit to list all keys)'). The tool description essentially repeats this info, adding no new semantic depth beyond what the schema provides.

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

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

The description opens with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly identifies the resource (saved values) and distinguishes from sibling tools by explicitly mentioning remember and forget as paired 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?

It states when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives and the workflow: 'Pair with remember to save, forget to delete.'

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

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

The description discloses that mark_read:true changes read state so subsequent calls see only newer events, and describes the returned payload fields (source, citation_uri, raw event). These details go beyond the annotations, and the optional mark_read side effect is transparently disclosed.

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, each with distinct information: what it returns, how to filter, and read-flag behavior plus an alternative endpoint. Nothing wasted.

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

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

Given no output schema, the description explains the return structure and provides usage patterns (filter, mark_read, polling). It also mentions the persisted feed and an accessible URL, making it self-contained 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?

The schema covers all five parameters, and the description adds examples (type 'sec_8k'), specifies 'since' as ISO timestamp, and explains mark_read's effect. It doesn't elaborate limit/unread_only, but the schema provides that, so this is above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement. It clearly denotes the tool's scope (recent alerts) and differentiates from sibling tools like list_subscriptions or recent_changes.

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' and offers an HTTP endpoint alternative for scripts/dashboards, giving clear usage context. However, it doesn't explicitly say when to prefer this over sibling tools, only when to use the HTTP endpoint.

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 the fan-out architecture, the GDELT→GNews fallback on rate-limit/5xx, the USPTO PatentsView API sunset causing a soft-fail, and the exact return structure. This is rich behavioral context.

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

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

The description is long but each sentence adds essential information. It front-loads user-facing query phrasings, then details sources, fallback behavior, and return format. No fluff, but it is dense enough that a slightly more compact structure could improve skimmability.

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

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

Given the tool's complexity and absence of an output schema, the description fully covers what the tool does, when to use it, how fallback works, input date formats, return shape, and the key alternative tool. There is no significant gap in contextual 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 input schema already covers all three parameters with 100% description coverage. The description adds extra meaning by explaining `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring, going beyond the schema.

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

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

The description clearly states this is a change feed for a company over a time window, with concrete query examples like 'what's new with X'. It explicitly distinguishes itself from sibling entity_profile by naming the alternative and its different use case.

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

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

The description provides explicit when-to-use phrasing ('What's new with X', 'latest on Y') and tells the agent to use entity_profile instead when a static profile is needed 'regardless of window'. This is an explicit alternative and exclusion.

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

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

Annotations provide idempotentHint=true and readOnlyHint=false, but the description adds substantive behavioral context: key-value storage scoping by identifier, persistence differences between authenticated and anonymous users (24-hour retention), and the ability to pair with recall/forget. 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 three sentences, each earning its place: purpose, usage triggers, and persistence details. It is front-loaded with the core action and avoids redundancy, making it easy to scan.

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

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

For a simple two-parameter key-value store with good annotations and no output schema, the description covers all essential aspects: purpose, when to use, persistence, scoping, and how to interact with related tools. Nothing critical 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 the schema fully documents both parameters. The description adds examples of what to store (resolved ticker, target address, user preference) but these are illustrative, not strictly necessary. Baseline 3 is appropriate as the schema already carries the semantic weight.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' This clearly distinguishes the tool from its sibling tools recall and forget, and the phrase 'across this conversation or across sessions' adds 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 explicitly states when to use the tool ('Use when you discover something worth carrying forward') and offers practical examples. It also names complementary tools: 'Pair with recall to retrieve later, forget to delete,' providing clear usage guidance versus alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes beyond by explaining internal cascading lookups, graceful degradation (LEI/FIGI enrichment degrades gracefully), and that unresolved identifiers are explicitly listed under 'unresolved'. This adds significant behavioral context beyond annotations, with no contradictions.

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

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

The description is quite verbose (multiple paragraphs) and includes implementation details like cascading and graceful degradation. While informative, it lacks front-loading of the core purpose; the first line consists of example queries rather than a direct statement. Could be trimmed for efficiency without losing meaning.

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

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

The tool has no output schema, and the description does not specify the exact JSON structure of the response. It mentions that identifiers are labelled with source and that unresolved items are listed under 'unresolved', but the agent lacks a clear picture of the return format. Given the complexity of the returned data (multiple identifier types), this gap reduces completeness.

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 good descriptions for both 'type' and 'value'. The free-text description adds further meaning by elaborating on each type (e.g., company includes CIK, ticker, LEI, FIGI; drug includes RxCUI) and providing input format examples (e.g., 'AAPL', '0000320193', 'ozempic'). This goes well beyond the baseline 3 expected from high schema coverage.

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

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

The description clearly states the tool resolves names to identifiers, with specific example queries (e.g., 'What's the ticker for...', 'find the CIK for...'). It distinguishes itself by recommending 'Use FIRST whenever you have a name but need an ID,' which sets it apart from sibling tools like entity_profile or compare_entities that handle already-resolved entities.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types (company, drug) and input formats. It lacks explicit 'do not use if' scenarios, but the positive direction is clear and actionable.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds value by disclosing that it 'probes each entity with ai_visibility_check,' ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary action and followed by a use case and return format. No wasted words; every clause contributes to understanding the tool's purpose and output.

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

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

Given 4 parameters and no output schema, the description provides a reasonable return format ('ranked list with score, confidence, signal density per entity') and a concrete use case. It omits details about models and _apiKey, but the schema covers those. It is sufficiently complete for an agent to recognize and invoke the tool correctly.

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

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

The input schema has 100% coverage, so all four parameters are already self-documented. The description does not add new parameter meaning beyond the schema; it reinforces the multi-entity comparison concept but does not explain individual parameters. 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: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check by focusing on multiple entities, naming the underlying probe tool, and stating it ranks results. The scope is explicit (brand + competitors), making the purpose unambiguous.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example query, implying this tool is for side-by-side comparison rather than single-entity checks. It does not explicitly name alternatives or exclusion criteria, but the context is strong enough to guide 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?

The description reveals behavioral traits beyond the annotations: it fans out to two external services, bundlephobia's first measurement can take 5-30 seconds, and partial failures degrade gracefully with sources_failed listing timed-out components. These details are not present in the annotations or schema, enhancing the agent's ability to anticipate runtime behavior.

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

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

The description is compact and well-structured, with each sentence serving a distinct purpose: composite function, usage triggers, return fields, and limitations/failure behavior. There is no filler or redundancy, maintaining high information density without bloat.

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 enumerates the summary block fields, auxiliary outputs (per-advisory detail, links, alternative versions), and error handling behavior. It also covers ecosystem limitations and performance caveats, making it fully contextual for a complex composite tool.

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

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

The input schema already covers both parameters (package name and version) with clear descriptions, so the schema coverage is 100%. The description only restates the version default and does not add extra semantic detail beyond the schema, meriting the baseline score of 3.

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

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

The description states a clear, specific purpose: a composite 'should I add this npm package to my project' check in one call, and names the two upstream services (deps.dev and bundlephobia) with their respective contributions. This goes beyond the generic title and makes the tool's uniqueness obvious relative to 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?

It gives explicit trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion rule for non-NPM ecosystems (PyPI/Maven/Cargo/Go), directing them to deps.dev:version directly, which is excellent 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 the tool read-only, idempotent, and non-destructive. The description adds beyond annotations by enumerating the exact fields returned (name, summary, record_count, owner/org, Feature Service url) and the chaining behavior. It doesn't disclose pagination or rate limits, but those are not critical given the safe, idempotent nature.

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, zero fluff. The first sentence states purpose with scope, the second details the return and gives a chaining hint. Front-loaded and efficient.

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

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

For a read-only search tool with no output schema, the description fully explains the return values and how the results integrate with other tools (query_layer/layer_info). It covers the essential behavior and workflow without unnecessary 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%, with each parameter (limit, query, org_id) already described. The description's mention of 'by keyword' aligns with the query parameter but adds no new parameter semantics. Baseline 3 is appropriate as 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 searches City of Brampton GIS open geospatial datasets by keyword, with specific examples of dataset categories. It distinguishes itself from siblings by describing the return payload (name, summary, record_count, owner/org, Feature Service url) and explicitly mentions query_layer / layer_info as downstream consumers, setting it apart as a discovery tool.

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

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

The description implies the tool is for initial dataset discovery and explicitly instructs to pass the returned url to query_layer / layer_info, providing a clear usage pattern. It does not explicitly state when not to use it, but the chaining guidance is strong and contextually sufficient.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), similarity metric (cosine), and the 200K-character cap with truncation behavior flagged. It also notes offsets for verification, adding rich behavioral context.

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

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

The description is concise and well-structured: it front-loads the core purpose, then usage guidance, then technical details. Every sentence adds value—purpose, use case, workflow, and implementation specifics—without redundancy or padding.

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 clearly states the return format: top-N passages with character offsets and similarity scores. It covers input constraints, algorithm details, and how to integrate with a related tool, making it complete for an agent to invoke correctly without missing 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?

Schema coverage is 100% with detailed descriptions for text, query, and limit. The description adds only contextual framing (e.g., 'text you already pulled', 'top-N passages') but no substantial new semantics beyond the schema. The baseline of 3 applies since the schema already carries the explanatory weight.

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 ('Semantic search') and a specific resource ('inside a fetched record'), with clear examples of input and output. It distinguishes itself from siblings by emphasizing it works on text the agent has already pulled, unlike tools that fetch documents. The pairing note with ask_pipeworx_grounded further clarifies its unique role.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded by explaining the intended workflow: fetch with gateway, then ground over relevant passages. This gives clear when-to-use and 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?

The annotations already mark this as a mutating, non-destructive, open-world operation. The description adds behavioral context such as the OAuth account requirement, phone verification for SMS, the 10/day SMS cap, and the always-on feed retrieval path. 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?

The description is a single dense paragraph, but it front-loads the core purpose and return value and every clause supplies actionable detail. It could be slightly restructured into bullets, and some type syntax is duplicated from the schema, so 4.

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

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

For a tool with nested delivery config and five subscription types, the description covers the main flows, auth, and key constraints, and the schema fills remaining details (webhook, patent_grant, clinical_trial). It does not describe failure/duplicate behavior, but the supporting schema and annotations provide substantial context.

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

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

The input schema already documents all three parameters with 100% coverage, but the description enhances meaning by mapping type-specific params to concrete examples (e.g., sec_8k items:['5.02'] = officer change, fred_series series_id:'UNRATE'). This adds value beyond the schema's raw 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream' and clearly states the return value ('Returns the new subscription id'). It sufficiently distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides clear usage context by explaining the OAuth requirement and by framing this as proactive monitoring versus pulling via recent_alerts. It does not explicitly spell out when not to use the tool or name alternative tools for listing/cancelling subscriptions, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is established. The description adds valuable behavioral context by disclosing that results are 'drawn from the live catalog of thousands of tools' and that each example includes 'the exact tool + argument shape that answers it.' This goes beyond the annotations to set expectations about output richness and dynamic nature.

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

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

The description is a single, information-dense paragraph. It front-loads with concrete example questions to ground the tool's purpose, and every clause contributes value (returns, tools, topics, usage). However, it reads as a long run-on sentence with em-dashes, which could be better structured with bullet points or shorter sentences for easier parsing. Still, it is appropriately sized for the tool's scope.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers what the tool returns, how to invoke it (no args for full spread, or with `topic`), and when to use it first. It also mentions the types of categories (company financials, drugs, etc.) and that results include tool+argument shape, leaving no critical gaps for an agent to select and call 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 input schema already provides 100% coverage of the single `topic` parameter, describing it as an 'Optional focus area' with allowed values. The description repeats these value examples and says it 'focuse[s]' the results, which aligns with the schema but does not add new semantic meaning beyond what is already documented. Thus, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('returns') and resource ('category-bucketed example questions'), and it is explicitly positioned as 'the onboarding entry point' that helps users discover what to ask. It distinguishes itself from sibling tools by noting it teaches how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter to focus the results, and implies that for direct queries users should use the actual tools after learning about them. This makes the when-to-use and how-to-use instructions clear.

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

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

With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds valuable behavioral context: the row is deactivated rather than deleted, and historical events remain available via recent_alerts. It discloses ownership enforcement without contradicting any 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 primary action ('Cancel a subscription by id'), and every sentence adds value. No fluff or redundancy.

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

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

Given the tool's low complexity (one parameter, no output schema) and the presence of annotations, the description covers all essential aspects: what it does, ownership constraints, and the deactivation behavior. The reference to recent_alerts also helps the agent understand downstream effects. This is complete for the tool's scope.

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 for 'id' is complete (100% coverage): 'Subscription id (uuid) returned by subscribe.' The description itself repeats 'by id' but adds no new meaning beyond the schema. This aligns with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription), and the title 'Unsubscribe from Alerts' reinforces this. It is distinct from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear usage context: ownership is enforced ('you can only cancel your own subscriptions') and it explains the effect on data (deactivated, not deleted). However, it does not explicitly name alternatives or state when not to use it, which keeps it just 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 annotations (readOnly, openWorld, idempotent), the description discloses critical behavior: the difference between "could_not_verify" (an error state) and "unsupported" (no source coverage), and insists that could_not_verify must not be shown as evidence. It also describes the routing fallback and enriched return value with citation, adding significant caller-relevant 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 long but every sentence earns its place. It is carefully structured: trigger phrases, purpose, use cases, routing, return values, an important error caution, and efficiency benefit. Despite the length, it remains scannable and information-dense, with no 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?

Given there is no output schema, the description fully explains the return values (verdict types, actual value with citation, reasoning) and error handling. It covers hidden complexities such as routing, fallback behavior, and error semantics. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by providing concrete examples for claim, and explaining tolerance_pct semantics (overrides implied tolerance, default cap at 5, and use for hallucination detection). This goes beyond what the schema alone provides.

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

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

The description opens with exact trigger phrases and defines the tool as "natural-language claim verification against authoritative sources." It clearly states it checks whether something a user said is factually correct, which is a specific verb+resource. It also differentiates from siblings by describing the verdict output and the fact it replaces a multi-step pipeline.

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

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

Explicit guidance is given: "Use whenever the agent needs to check whether something a user said is factually correct." It also details routing logic (company-financial vs. other claims) and notes it replaces 4–6 sequential calls. However, it does not explicitly name alternative tools or state when not to use it, though the conditions are fairly inferable.

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