Arcgis Eagan

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

The description discloses that the tool makes external LLM calls, including a BYO-key Anthropic path where the user pays Anthropic directly, which is beyond the annotations. It also reveals the return shape: per-model {score, confidence, signals, raw_response} plus a combined view. This aligns with the read-only and open-world hints and adds actionable 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 three sentences, front-loaded with the core action, then adds cost and return details, and ends with use cases. No redundant phrases; every sentence provides distinct value.

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

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

Given there is no output schema, the description carries the full burden of explaining returns, and it does so with a concrete object shape. It specifies required input, optional model selection, key handling, and applicable use cases. This is complete enough for an agent to invoke the tool correctly.

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

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

The input schema already covers all parameters with detailed descriptions (100% coverage), including the default model and the `_apiKey` requirement. The description repeats the default model and key condition but does not add any new semantic detail beyond the schema, so it stays at the schema-driven baseline of 3.

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

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

The description uses the specific verb 'probe' and clearly defines scope: 'what they know about a business / brand / product / topic' and the output 'score visibility (0-100) per model.' This distinguishes it from siblings like ask_pipeworx (internal knowledge) and scan_competitor_ai_presence (competitor-specific focus). The title and description align well.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and the BYO-key condition for Anthropic, which guides invocation. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds substantial behavioral context: it routes to a large set of tools, fills arguments, returns structured answers with citation URIs, and notes it works on every tier with one fast call. This goes well beyond the annotation baseline, though it could mention limitations or failure modes.

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

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

The description is long but well-structured and front-loaded with 'PREFER OVER WEB SEARCH'. Each segment adds value: domain list, trigger phrases, examples, and escalation instructions. It is somewhat verbose and could be trimmed, but no sentence is 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?

For a complex meta-tool with no output schema, the description is remarkably complete. It covers what the tool does, when to use it, how it behaves (routing, citations), examples, and when to escalate to siblings. It also addresses breaking news and multi-source scenarios. There are no major gaps.

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

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

The input schema covers all parameters thoroughly, with 'question' and five aliases (q, text, input, query, prompt) each described. Since schema description coverage is 100%, the baseline is 3. The description does not add parameter-specific detail beyond the schema, so no extra credit is warranted.

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 answers factual questions about current/historical data across a wide range of domains, with a specific verb ('routes', 'returns'), resource scope ('5,529 tools across 1455 verified sources'), and explicit differentiation from sibling tools like ask_pipeworx_grounded and deep_research. It also provides concrete examples and phrases like 'START HERE', making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('Use whenever the user asks "what is", "look up", ...'), explicitly names alternatives and when to step up to them (ask_pipeworx_grounded for verbatim evidence, deep_research for broad multi-part questions), and states 'PREFER OVER WEB SEARCH'. This is exemplary usage guidance.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the beta status, that candidate routing improvements may be active, and that it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router with no fallback, adding transparency about its experimental edge.

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

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

The description is four sentences and under 90 words, efficiently front-loading the beta identity and then providing all needed operational context. No word is wasted; each sentence explains a unique aspect: identity, current state, usage, and fallback.

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

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

For a tool with no output schema, the description sufficiently covers behavior: identical to ask_pipeworx, full router, experimental, and subject to comparison testing. It also notes the response shape is identical, so an agent knows what to expect. The annotations already handle 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?

The input schema fully documents all six parameters as aliases for 'question', with 100% coverage. The description does not add parameter-level details, so the baseline of 3 applies as the schema already provides complete semantics.

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

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

The description explicitly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It goes beyond a simple verb to explain what the tool does and how it differs from the stable counterpart, making its purpose unmistakable.

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

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

The description directly instructs to use it exactly like ask_pipeworx when wanting the newest routing. It also mentions that results are compared against the stable router, giving context for when this experimental version is appropriate. While it doesn't list explicit exclusions, the conditional 'when you want the newest routing' implies the stable version is for other cases.

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 the internal mechanism: routes to tools, fills arguments, fetches data, then extracts the answer strictly from tool output. It also details the exact refusal reasons (not_in_source, no_tool_match, etc.) and the extra LLM call cost, which goes well beyond the readOnlyHint/idempotentHint annotations. No contradiction exists.

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

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

The description is well-organized: it opens with a precise purpose statement, then details the mechanism, return/refusal structures, and closes with usage guidance and cost comparison. Every sentence earns its place without redundancy or 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 having no output schema, the description thoroughly documents the success/refusal return shapes, enumerates all refusal modes, explains the routing/extraction pipeline, and provides context on when to prefer the sibling tool. It is fully self-contained for an agent to invoke correctly.

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

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

The schema already provides 100% coverage, including descriptions for all six parameters (question and five aliases) with the phrase 'Your question in natural language.' The description adds no new parameter-level nuance beyond what the schema states, 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 this is a 'hallucination-resistant answer mode for high-stakes reads' that routes to the same tool selection as ask_pipeworx but extracts answers only from tool results. It distinguishes from its primary sibling by name and explains the grounded extraction behavior, making its purpose unambiguous.

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

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

It explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and contrasts with ask_pipeworx by noting the extra LLM call and recommending 'prefer ask_pipeworx for casual lookups.' This provides clear when-to-use/when-not-to-use guidance and names an alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: low-confidence matches short-circuit with status, closed markets return market_closed_or_inactive, wide-spread markets get tradeability warnings, and cancellation-rule risk is parsed. It also discloses failure fallbacks (GDELT 429s, GNews backfill) and the resolver contract. This goes far 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?

Although the description is long, it is exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Every sentence adds actionable value, whether it's listing classifiers, giving fan-out examples, or explaining safety mechanisms. It earns its length.

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

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

With no output schema, the description must explain return values and edge cases, and it does so thoroughly. It covers market/analysis/evidence shapes, resolver confidence levels, parent_event extraction, news fallback fields, safety short-circuits, and resolution-rule risk. It also gives concrete examples across bet categories, making it fully complete for an agent to invoke correctly.

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

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

The input schema has 100% coverage for all three parameters (market, depth, include_raw), including accepted formats and defaults. The description doesn't add significant parameter-level meaning beyond the schema; it focuses on tool behavior and output shapes. Baseline 3 is appropriate because the schema already carries the parameter semantics.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details resolution, classification, fan-out, and output (evidence packet + market-vs-model comparison), clearly distinguishing it from sibling tools like polymarket_edges or deep_research. The explicit use-case list ('should I bet on X', etc.) reinforces purpose.

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

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

The description gives explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides many domain examples (BTC, Fed, Hormuz, Yankees, etc.). However, it does not explicitly state when NOT to use the tool or name alternative sibling tools, so it stops short of a 5.

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

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

Even with annotations declaring read-only, open-world, and idempotent behavior, the description adds substantial context: data sources (SEC EDGAR/XBRL vs FAERS), metric handling (off-calendar fiscal years), sorting behavior, and output shape (paired data + citation URIs). This goes far beyond what annotations provide and contradicts nothing.

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

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

The description is front-loaded with trigger phrases and uses compact bullet-like clauses. It is somewhat dense but every sentence adds value—examples, data sources, edge-case handling, and output details—without fluff.

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

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

For a tool with no output schema, the description sufficiently explains return values (paired data, citation URIs, sorted by primary metric) and covers both entity types' data sources and nuances. It is complete enough for an agent to select and invoke the tool correctly with confidence.

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

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

The schema already covers both parameters thoroughly (enum for type, min/max for values). The description enriches this by explaining what each entity type returns (revenue/net income for companies, adverse-event/trial counts for drugs) and how results are sorted, adding practical meaning beyond field descriptions.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2-5 entities (companies or drugs) in a single parallel call. Trigger phrases and explicit distinction from sequential single-pack lookups make its function unmistakable and differentiate it from sibling tools 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?

The description explicitly states when to prefer this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides concrete usage examples. It also clarifies entity-specific behavior and limits (2-5 entities), giving the agent clear decision criteria.

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

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

Goes far beyond the annotations by disclosing the internal decomposition/routing process, return packet contents (verbatim evidence, confidence, source, fetched_at, citations), gap handling (explicit gaps[], never invented), depth-level behaviors (hop/recovery, contradictions[]), semantic excerpting, and latency expectations. No contradiction with the readOnly/openWorld/idempotent annotations; the 'NOT open-web search' clarifies scope without negating that it pulls live external data.

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

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

The description is long but every sentence carries important context—account requirements, sourcing, alternatives, depth modes, latency, and return format—so it is information-dense rather than padded. It loses one point for being somewhat sprawling and repeating depth details already present in the schema, but it remains well-structured and front-loaded with the most critical caveat (account requirement).

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

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

With no output schema, the description fully explains the return value: a findings packet with citations, gaps, contradictions, hop field, and semantic excerpting. It also covers edge cases (topics not in structured catalog, long records) and latency, making it complete for an agent to anticipate behavior and results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by elaborating on the 'depth' parameter (what quick/standard/thorough each do behaviorally) and gives example questions for 'question'. This exceeds the schema's own field descriptions and helps the agent pick appropriate depth values, though it does not add anything for the question parameter beyond what's already obvious.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly distinguishes itself from siblings with 'this is NOT open-web search' and clear contrasts to ask_pipeworx. It tells the agent exactly what it does and when it is the right choice.

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

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

Provides explicit usage guidance: best for broad/multi-part questions over structured data, with concrete examples. It names alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx') and includes account/plan prerequisites, leaving no ambiguity about when to invoke this tool vs its siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description is consistent. Beyond that, the description discloses useful behavioral traits: it returns top-N relevant tools with 'names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed.' This adds meaningful context about return format and latency savings.

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 yet comprehensive, covering purpose, domain scope, return format, and usage timing in three sentences. It front-loads the core verb and object while avoiding redundant filler. Every sentence serves a distinct function: what it does, what it returns, when to call it.

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

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

Given the tool's moderate complexity and absence of output schema, the description fully covers what an agent needs: it explains the return payload (top-N tools with schemas/examples) and the 'ready to call directly' benefit. Annotations cover safety, and the alias system is documented in the schema, so the description is complete for effective selection and invocation.

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

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

Schema description coverage is 100% with detailed parameter descriptions and examples, so the baseline is 3. The description adds minimal parameter-level detail beyond the schema, though 'top-N' hints at the limit parameter. Since all parameters (including aliases) are already well documented, no additional compensation is needed.

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 verb+resource statement: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.), making the scope explicit. This clearly distinguishes it from sibling data-specific tools by positioning it as the discovery/search tool for the option set.

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 exactly when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist.' It also gives explicit prioritization: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides strong guidance without naming specific alternatives, which is appropriate given the broad sibling list.

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), it discloses parallel fan-out, return fields, the USPTO sunset with soft-fail behavior, and GDELT→GNews fallback. This adds significant behavioral context not present in the schema or annotations, and does not contradict 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 dense and informative, but the five example queries in the opening are somewhat redundant. Still, the structure front-loads the purpose and usage, and every sentence carries functional weight, though a more streamlined opening would earn a 5.

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

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

Given the complexity and absence of an output schema, the description explains the return fields and data sources in detail (CIK, filings with URIs, fundamentals, patents with sunset, news with fallback, LEI). It could be more complete with explicit error handling or rate limits, but it is sufficiently thorough for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the description mostly repeats the schema's parameter details (ticker/CIK, names not supported). It adds illustrative examples but no additional semantic depth beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description uses a clear verb phrase ('full cross-source profile') and specific resource ('US public company'), and distinguishes itself by stating it is preferred over chaining single-pack lookups. It also contrasts with resolve_entity for names, 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 explicit 'when to use': 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives an exclusion and alternative: 'names not supported (use resolve_entity first if you only have a name).' This is clear guidance relative to siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. It adds use-case context (clearing sensitive data) but does not disclose extra behavioral traits like error handling or permanence beyond what the annotations imply. No contradiction.

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

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

The description is two sentences long, front-loaded with the core action, and free of unnecessary details. Every clause adds value: the first states the operation, the second gives usage context and sibling tool references.

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 good annotations and schema coverage, the description is nearly complete. It covers the operation, usage triggers, and relationship to related tools. It could mention what happens if the key is missing or whether deletion is permanent, but this is minor given the tool's simplicity.

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

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

The input schema already documents the 'key' parameter with 'Memory key to delete' at 100% coverage. The description adds no additional parameter-specific meaning, only restating the deletion action. This is the baseline expected score when schema covers all 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: 'Delete a previously stored memory by key.' It uses a specific verb (delete) + resource (memory) and distinguishes it from sibling tools like remember and recall by explicitly contrasting deletion with storage/retrieval.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references alternatives by saying 'Pair with remember and recall,' making the use case 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format, plus states the output is a single text blob ready for site-root placement. This goes beyond the annotations, though edge cases and error handling are not addressed.

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 main purpose and process. The first sentence covers what and how; the second lists concrete use cases. Every word earns its place, with no filler 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?

For a simple two-parameter tool with full schema coverage and no output schema, the description covers input, process, output format, and use cases. It even preempts the return type by stating 'Output is a single text blob'. This is complete given the tool's low complexity.

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

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

Schema description coverage is 100%, meaning both url and max_links already have clear descriptions in the schema. The description mentions 'any URL' which reinforces the url parameter, but it does not add new meaning about max_links or parameter syntax. This meets the baseline for a well-documented schema but does not exceed it.

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

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

The description uses a specific verb 'Generate' with a clear resource ('production-ready llms.txt file') and outlines the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on auditing AI presence rather than producing a file.

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

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

The 'Useful for' list provides three concrete use cases: getting a client's site indexed, drafting llms.txt for your own project, and auditing competitor AI presence. While it doesn't explicitly name alternative tools or state when not to use this tool, the contexts are clear and help an agent select it over siblings. The lack of exclusionary guidance prevents 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 and idempotentHint=true, so the safety profile is known. The description adds value by specifying the exact information returned (fields, geometry type, record count, capabilities), which gives the agent a clear picture of the tool's output. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence with every word earning its place. It immediately states the action and resource, then compactly lists the output. 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?

For a simple one-parameter read-only tool with strong annotations, the description is complete. It fully covers what the tool returns and the type of input expected. No output schema exists, but the description explicitly lists return components, so no ambiguity remains.

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 with a well-described 'url' parameter and an example. The description adds no new parameter semantics beyond the schema, but the schema is fully sufficient. 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 states a clear, specific verb+resource: 'Get an ArcGIS Feature/Map Service layer's schema by url.' It also enumerates what is returned (fields, geometry type, total record count, capabilities), distinguishing it from sibling tools like query_layer that retrieve data.

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

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

The description clearly implies when to use the tool: when the schema or metadata of an ArcGIS layer is needed. It provides clear context without exclusions or explicit alternatives, but the purpose statement itself is sufficient for an agent to select this tool over data-querying siblings.

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

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

Annotations already declare readOnly=true and destructive=false. The description adds valuable context: it specifies the return fields (id, type, params, etc.), defaults to active subscriptions, and scopes results to the caller. This goes beyond the annotation-provided safety profile.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by return fields and usage guidance. Every sentence contributes value with no redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the purpose, return values, and usage. It could mention potential pagination or limits, but that omission is minor for a typical subscription listing.

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 only parameter include_inactive with its default. The description reinforces the active/inactive distinction but does not add meaningful new semantics beyond the schema.

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

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

The description clearly states the verb 'list', the resource 'subscriptions', and the scope 'caller's active subscriptions'. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing rather than mutating.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for using before subscribe or unsubscribe actions, effectively guiding tool 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?

Goes well beyond the minimal annotations (all false). Discloses the claim_token flow for later status checks, daily digest processing, rate limits (5/day/identifier), and that it's free and doesn't count against tool-call quota. Also warns that reporting other servers' issues will only delay resolution. 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 the tool's behavior is complex (multiple feedback types, claim tokens, exclusions, rate limits). It's front-loaded with purpose and usage. Minor redundancy in the 'ONLY for Pipeworx tools' point repeated later, but no wasted sentences.

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

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

No output schema exists, so the description must explain return values — it does (claim_token, later status). It also covers rate limits, quota impact, and the team's workflow. For a feedback tool with nested context objects, all essential operational details are present.

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 schema carries the parameter documentation. The description adds a usage pattern for claim_token (pass it back later to read status), but doesn't substantially expand on the schema's parameter descriptions. 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: telling the Pipeworx team about broken, missing, or desired functionality. It uses specific verbs ('tell', 'broken', 'missing', 'needs to exist') and distinguishes it from siblings like ask_pipeworx or discover_tools by focusing on feedback about Pipeworx tools/packs.

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 when-to-use guidance: bugs, feature/data_gap, praise. Also explicit when-not-to-use: tools from other MCP servers. Includes a decision heuristic for uncertain cases ('Not sure? Pipeworx tool names are the ones this connection lists'). This is modeled after the high-quality TDQS examples.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses meaningful behavioral traits: the data is cached for 5min-1h depending on window, it is derived from CF analytics-engine with no PII, and the output is limited to (pack, tool, count). This adds valuable context about freshness, provenance, and privacy.

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

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

The description is front-loaded with the core purpose and then provides a list of use cases and a note on the data source/caching. While the 'Useful for' list is slightly lengthy, every clause adds useful information, and the overall structure remains focused 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?

The tool has a single optional parameter, strong annotations, and no output schema. The description covers the return content (top tools, top packs, total call volume), window selection, data source, caching, and privacy, making it complete for the tool's complexity and leaving no critical gaps.

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

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

The schema already provides a thorough description of the window parameter, including the enum values, default (24h), and the semantic difference between shorter and longer windows. The tool description restates this information but does not add any additional meaning beyond what the schema already covers, so a baseline 3 is appropriate.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume' from what other AI agents are calling on Pipeworx. It uses a specific verb ('returns') and resource, and the framing around trending agent activity distinguishes it from sibling tools like discover_tools or search_datasets.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a popular tool is the canonical choice, and seeing alignment with agent needs. It provides clear context for when to use the tool, though it does not explicitly state alternatives or exclusion criteria.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description enriches behavior disclosure with concrete thresholds (e.g., deviations >3pp, Jaccard ≥0.30), filtering rules (placeholder slugs, >20% placeholder returns null), and the FILL CHECK explaining how the signal is priced against live CLOB depth. It also details response fields and the 'do not trade' condition, adding significant context beyond the annotations.

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

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

The description is long but well-structured: it flows from general purpose to mode-specific usage, followed by semantic anchor, partition filter, response, and fill check. Each section earns its place given the tool's complexity. It is not overly terse, but every sentence conveys necessary detail, so a 4 is appropriate rather than a 5 for extreme efficiency.

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 entirely covers response contents (opportunities[] and partition_check fields). It explains all three invocation modes, the fill-check caveat, and the relationship to sibling tools. For a tool with two optional parameters and multiple operational modes, this description is thorough and complete, leaving no critical gaps for an agent to misuse 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?

The schema coverage is 100% and both `event` and `topic` have descriptions, but the tool description dramatically expands their semantics: it gives slug examples, explains that full URLs are accepted, describes the event traversal and partition check, and details the topic's cross-event search and similarity requirements. This far exceeds the baseline expectation for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (`trending_scan`, `event`, `topic`) and differentiates from sibling tools like `polymarket_fill_risk` by pointing to it for custom sizing. The purpose is unambiguous and mode-specific.

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

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

The description provides explicit when-to-use guidance for each invocation style: '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.' It also explains tradeoffs (e.g., cross-event catches date patterns single-event misses), when not to trade (`realizable_edge_pp ≤ 0 … do not trade it`), and refers to an alternative (`polymarket_fill_risk`). No exclusions are omitted.

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 extensive behavioral details beyond the readOnlyHint/idempotentHint annotations: caching ('Cached 1h at the KV level'), internal segment logic (placeholder filtering, partition overround adjustments, longshot gates), and a 24h-move warning. It also explains the fed_candidates exclusion rationale. No contradictions with annotations.

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

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

The description is front-loaded with a clear purpose statement and uses visible structure (CAPITALIZED segments, numbered list, top-level response fields). However, it is quite long and includes dense parenthetical details (e.g., per-sport alpha values, prior run constants) that could be trimmed without losing core guidance. Still, the organization is strong.

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

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

With no output schema, the description fully compensates by specifying the response top-level fields (by_segment, fed_candidates/fed_note, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and why segment emptiness can occur. It also explains the knobs and caching behavior, making the tool fully actionable.

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

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

The schema already has 100% coverage with thorough descriptions, but the tool description adds valuable semantics: it explains why min_kelly can't filter partition arbs (parent-level kelly_fraction_half=0), how min_partition_leg_kelly differs, and elaborates on slippage assumptions (zero fees but 20-50bp execution costs). This goes beyond simple schema repetition.

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 immediately states a specific verb+resource ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and clearly distinguishes this from the broader toolset by detailing three model families and use case ('what should I bet on today'). The purpose is unambiguous and well-scoped.

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 strong usage context: designed for daily opportunity discovery, avoids paging hundreds of markets, and explains how knobs filter results (min_liquidity/max_spread_pp, min_partition_leg_kelly). However, it does not explicitly mention alternative tools like polymarket_arbitrage or when not to use this tool, so it lacks explicit exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses specific behaviors: history is bounded by a 60-day TTL, snapshots are written on cache-miss (so gaps mean no scan), decay is derived from daily closes not intraday, and the median lifespan is a 'competition clock.' No contradictions with annotations.

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

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

The description is long but well-structured: purpose, parameters, response fields, limitations. Each sentence adds substantive info, especially given no output schema. It's front-loaded with the core question and doesn't waste words, though it could arguably be trimmed slightly.

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

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

With no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and key calculations (decay_pp_per_day, trend). It also covers data availability and limitations, making the tool self-contained for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly repeats parameter details (days default/max, window default) with slightly less specificity (max 30 vs clamp 2-30). It adds little beyond the schema, but does clarify window as 'snapshot family' and days as 'lookback' context.

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

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

The description states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and a clear question ('how long has this edge existed and is it shrinking?'). It distinguishes from siblings like polymarket_edges by focusing on persistence/decay, not just current edges.

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

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

The description gives an implicit use case: to differentiate fresh vs stale edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), which tells the agent when to consult this tool. It does not explicitly name alternatives, but references its base dataset (polymarket_edges) and explains snapshot gaps, providing practical 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 annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context beyond that: it walks the CLOB order book, returns a verdict, highlights thin legs, warns about partial basket fills converting arb into unhedged directional positions, and explains how size_usd is interpreted differently across modes. 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 tightly packed with necessary detail, using uppercase mode labels and explicit directive language. Every sentence contributes: mode definitions, parameter interpretations, output field lists, risk rationale, and usage thresholds. For a complex tool with no output schema, this level of density is appropriate, not wasteful.

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

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

Given the tool's complexity, 4 parameters, no output schema, and high-stakes usage, the description is remarkably complete. It covers both modes, all relevant output fields, edge-case risk behavior (per-leg details, thin_legs, forced_directional_risk), and the economic motivation. There are no significant gaps that would prevent an agent from selecting or using this 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?

While the input schema covers all 4 parameters, the description adds critical semantics: the exclusive-or requirement between market and event, the full meaning of side values in each mode, and the dual interpretation of size_usd (max spend vs target proceeds vs settlement notional). This goes far beyond schema descriptions and is essential for 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 opens with a specific verb and resource: "Realizable-vs-theoretical edge check against live CLOB order-book depth." It clearly distinguishes this from sibling tools by naming polymarket_arbitrage and polymarket_edges and positioning fill risk as the pre-trade validation step.

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 when-to-use guidance is given: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also describes two distinct modes (single-market vs basket) and the conditions under which each applies, making alternative selection unambiguous.

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

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

Even with annotations indicating a safe read-only operation, the description adds substantial behavioral detail: compatibility_warning conditions, temporal_alignment implications (aligned:false means spreads are meaningless), and skipped_cross_type/subtype counters exposing dropped comparisons. This goes well beyond the annotation hints and helps the agent interpret unusual results.

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). It is front-loaded with the core purpose and every sentence carries distinct information. It could be slightly more concise by trimming redundant warnings, but it remains efficiently organized for a complex tool.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread, top_spreads_pp) and safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases about mismatched bet shapes and temporal misalignment, making the description complete enough for an agent to invoke and interpret the tool correctly.

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

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

The schema already provides 100% coverage for each parameter, so the baseline is 3. The description adds value by explaining that topic accepts pre-mapped macro keywords, and that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, clarifying relationships between parameters beyond their individual 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 uses a specific verb+resource: "Cross-venue spread between Kalshi and Polymarket for the same resolving question," which clearly defines what the tool does and distinguishes it from siblings at other venues. It further details two modes (topic shortcut and explicit pairing), narrowing the purpose precisely.

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

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

The description explicitly explains when to use each mode: topic shortcuts for pre-mapped macros and explicit tickers/slugs for custom pairings. It also provides important use expectations: "Real cross-venue spreads are rarer than the macro-shortcut list suggests" and warns that pre-mapped topics may not be tradeable. It does not explicitly name alternative tools for exclusion, but the context is clear enough.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds value by stating the return format: 'Returns attribute rows (and geometry).' It also characterizes the where clause as 'SQL-like,' which provides behavioral insight into query semantics. This exceeds the baseline for annotation-covered tools.

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 at three sentences, front-loaded with the purpose, followed by parameter highlights, return format, and a usage tip. Every sentence earns its place with no redundancy or fluff. The formatting of code-like terms (where, out_fields, etc.) is consistent and readable.

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

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

For a read-only query tool with full schema coverage, the description provides sufficient context: it ties the url to search_datasets, explains the return format (rows and geometry), and offers a sampling pattern. Even without an output schema, the agent can predict the tool's behavior and integrate it into a workflow. Missing pagination details are available in the schema via offset/limit.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces key parameter semantics like 'SQL-like where' and 'comma-separated out_fields,' but these are already present in the schema. It does not introduce additional parameter details beyond what the schema provides, so the score stays at baseline.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets).' The verb 'Query' specifies the action, and the resource is explicitly an ArcGIS layer. This distinguishes it from sibling tools like layer_info (metadata) or search_within (spatial search), especially with the reference to search_datasets as a data source.

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 indicating the url should come from search_datasets, placing the tool in a workflow. It also gives a practical sampling tip: 'Use where="1=1" + out_fields="*" to sample.' However, it does not explicitly mention when not to use this tool or recommend alternatives like layer_info for metadata, 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. The description adds valuable behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and describes the two operational modes (retrieve by key, list all keys). No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with the primary action, and every sentence provides essential information. There is no redundancy or filler, making it highly concise and well-structured.

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

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

For a simple tool with one optional parameter and strong annotations, the description is complete. It covers purpose, usage context, scoping, and relationships to siblings. No output schema exists, but the return values are implicitly understandable from the description.

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

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

The schema already provides a clear description for the 'key' parameter: 'Memory key to retrieve (omit to list all keys)'. The description repeats this functionality but adds no new parameter-specific semantics. Since schema coverage is 100%, 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 function: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses specific verbs (retrieve, list) and identifies the resource (saved keys/values). It also distinguishes itself from related sibling tools by explicitly referencing 'remember' and 'forget'.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and companions: 'Pair with remember to save, forget to delete.' This clearly positions the tool relative to siblings and gives concrete scenarios.

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 contradicts the annotation readOnlyHint=true by explaining that setting mark_read:true flags events as read and that the next call only shows newer ones. This is a persistent state mutation, not purely read-only. Therefore the description directly contradicts a structured annotation, and the transparency score must be 1 per the rubric.

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

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

The description is three sentences and front-loaded with the core purpose. It includes useful details about return payload and filtering, plus an alternative access URL. Every sentence contributes meaning, though the final URL sentence is somewhat tangential to using the tool itself. Still, it is concise and well-structured.

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

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

With five parameters and no output schema, the description covers the expected return values (source, citation_uri, payload), the mark_read side effect, and the polling use case. It also mentions the parallel HTTP endpoint, which aids context. The only significant gap is the annotation contradiction, but structure and content are otherwise complete enough for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example for type ("sec_8k"), explains the since parameter (ISO timestamp), and clarifies the side effect of mark_read. However, it does not add meaningful semantics for limit or unread_only beyond the schema, so it stays at the baseline.

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

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

The description starts with 'Pull fired events from your subscription feed,' which is a specific verb+resource pairing. It clearly distinguishes this from siblings like list_subscriptions (list subscriptions) and recent_changes (changes to something else), and it details what each alert contains (source, citation_uri, raw payload).

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: it is for pulling fired events, filtering by type/since, and marking as read. It explicitly mentions that polling works fine and points to an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools or state when not to use this tool, so it lacks exclusionary 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 discloses fan-out to three APIs, the GDELT→GNews fallback behavior, USPTO soft-fail due to PatentsView API sunset, and return structure (changes[], total_changes, citation URIs). Annotations already declare read-only/idempotent, so this adds valuable operational context beyond annotations.

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

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

The description is relatively long (~100 words) but dense with behavior and usage. The opening query examples and parameter format repetition slightly overlap with schema, but overall every sentence contributes meaningful context. Could be tightened but is acceptable for the tool's complexity.

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

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

Given the tool's complexity (multiple sources, fallback logic, no output schema), the description is thorough. It covers return shape, source-specific behavior, API sunset implications, and differentiates from a sibling tool. This provides sufficient context for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description repeats the `since` format and `value` options (ticker/CIK) without adding new parameter semantics beyond the schema. The only slight addition is recommending '30d' or '1m' for typical monitoring.

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 user-facing query examples ('What's new with X') and defines it as a 'change feed for a company in the last N days/weeks/months'. It names the specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from 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?

The description provides concrete use-case triggers and explicitly advises when to use an alternative: 'Use entity_profile instead when you want the static profile...'. It also explains operational fallbacks (GDELT preferred, GNews when rate-limited) and the soft-fail condition for USPTO.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond these hints, such as scoping ('scoped by your identifier') and persistence behavior ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). 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 well-structured sentences, front-loaded with the core purpose, then usage guidance, then technical context and companion tools. Every sentence adds information; 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?

This is a simple two-parameter tool with no output schema. The description fully covers the operation's context: when to use, persistence and auth behavior, identifier scoping, and how it fits with related tools. No additional information seems necessary.

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

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

The schema already provides 100% description coverage for both parameters ('Memory key' and 'Value to store'), so the baseline is 3. The description adds minor context by giving examples in the main text and explaining the key-value pair scope, but it doesn't add significant meaning beyond what the parameter descriptions already convey.

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

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

The description states a specific verb ('Save data') and resource ('data the agent will need to reuse later'), making the tool's purpose clear. It also distinguishes itself from siblings by explicitly mentioning companions: 'Pair with recall to retrieve later, forget to delete.' This clearly positions the tool within the memory family.

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 context: 'Use when you discover something worth carrying forward' and gives concrete examples such as 'a resolved ticker, a target address, a user preference.' It also names alternatives and complementary actions ('recall', 'forget'), fulfilling the usage guidelines dimension.

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

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

Despite having annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds rich behavioral context: cascading multiple lookups, cross-source identity spine, labelling identifiers with source, explicitly stating unresolved identifiers, and graceful degradation when LEI/FIGI sources are unavailable. This far exceeds 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 long but every sentence contributes: opening examples establish intent, the 'Use FIRST' directive gives placement, and the SUPPORTED TYPES breakdown is organized with detail. No redundancy or fluff.

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

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

With no output schema, the description fully explains return values (CIK, ticker, LEI, FIGI, RxCUI, ownership, citations, unresolved list), potential failure modes (degradation, unresolved identifiers), and the internal cascading behavior. It provides a complete mental model for an agent.

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

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

Schema description coverage is 100%, so parameters are fully documented there. The description adds minor context (e.g., examples like 'AAPL' and 'ozempic') but does not meaningfully enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: resolving a user-spoken name to canonical/official identifiers required by other tools. It distinguishes itself from siblings by noting 'other tools require as input' and says 'Use FIRST whenever you have a name but need an ID'.

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

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

It explicitly directs when to use the tool ('Use FIRST whenever you have a name but need an ID'), provides example queries in the opening line, and clarifies that using it replaces 2-3 manual lookups, giving the agent clear selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds valuable behavioral context: it reveals the probe mechanism (ai_visibility_check), the ranking logic, and what is returned (ranked list with score, confidence, signal density). No contradiction with annotations.

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

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

Three sentences, front-loaded with the core purpose. Every sentence adds value: definition, mechanism, use case, and return format. 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?

The description covers the tool's purpose, process, use case, and output format. Even though there is no output schema, it explicitly states what is returned. Given the annotations and full schema, this description is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description does not add parameter-level detail beyond the schema, but it does provide overall context that helps interpret the entities parameter. Baseline 3 is appropriate since 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 uses a specific verb ('Compare AI visibility') and resource ('multiple entities side-by-side'), clearly distinguishing this from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison). It also explicitly names the sub-tool ai_visibility_check and the ranking behavior, leaving no ambiguity about what the tool does.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an illustrative question, and implies the alternative (ai_visibility_check for single entities) by emphasizing 'multiple entities'. It does not explicitly state when not to use it, but the context is strong 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?

Beyond the readOnly and idempotent annotations, the description discloses partial failure behavior (bundlephobia timeout, sources_failed), latency (5-30s first measurement), and the composite fan-out across two services. This gives the agent important expectations about performance and failure handling.

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

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

The description is multi-sentence but well-structured, front-loading the core purpose and usage, then adding return details, ecosystem scope, and failure behavior. It's longer than strictly necessary but each sentence carries unique value.

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

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

Without an output schema, the description lists all key return fields (summary block, per-advisory detail, links, alternative versions) and explains the degraded behavior on failure. Combined with annotations, the agent has a full picture of what happens when the tool is called.

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

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

The input schema already has 100% coverage for both parameters, describing package name and version defaults. The description adds minimal parameter-specific detail; the mention of 'new version' latency is more behavioral than semantic. Thus, a baseline 3 is appropriate.

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

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

The description clearly states this is a composite check for whether to add an npm package, listing specific data sources (deps.dev, bundlephobia). It distinguishes itself by specifying the npm ecosystem scope and alternative handling for other ecosystems, though it doesn't name a specific sibling 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?

Explicitly says 'Use whenever an agent asks...' and gives concrete examples ('is X safe / popular / small'). It also states exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' guiding users to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact return fields (name, summary, record_count, owner/org, Feature Service URL) and downstream usage, which goes beyond the minimal annotation 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 two sentences, front-loaded with the action, and every sentence earns its place. It efficiently conveys purpose, scope, return values, and the intended downstream workflow.

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 3 optional parameters and no output schema, the description fully explains the tool's purpose, return format, and how it connects to sibling tools (query_layer / layer_info). It provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (all three parameters have descriptions), so the baseline is 3. The description's mention of 'keyword' aligns with the 'query' parameter but adds no additional semantic detail beyond what the schema already provides.

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

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

The description uses a specific verb ('Search') and identifies the exact resource ('City of Eagan GIS open geospatial datasets') with example categories. It clearly distinguishes this tool from siblings by stating it returns dataset metadata and a Feature Service URL, which can then be passed to query_layer/layer_info.

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 mentions a workflow: pass the returned URL to query_layer / layer_info, which implies when to use those alternatives. It provides context for the search capability but does not explicitly state when NOT to use this tool or exhaustive exclusions.

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

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

The description discloses non-obvious behavior beyond the readOnlyHint/idempotent annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and that passages include offsets and similarity scores. This gives the agent a realistic model of how results are produced.

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

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

The description is four sentences, front-loaded with the core action, and progresses logically from purpose to usage to technical details. Every sentence provides distinct information—no filler or redundancy.

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

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

With no output schema, the description adequately specifies return values (passages with offsets and similarity scores), input limits, and alignment with ask_pipeworx_grounded. It gives an agent enough understanding of the tool's behavior and trade-offs 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 coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for text (SEC 10-K body, article) and clarifying that limit returns 'top-N passages.' This enriches the bare schema definitions, even though it doesn't fundamentally redefine them.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly specifying the action and resource. It distinguishes itself from siblings like deep_research or ask_pipeworx by focusing on searching within user-supplied text and explicitly pairs with ask_pipeworx_grounded, reinforcing 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?

It provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and 'search_within saves context.' It also names an alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear decision 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?

Adds significant behavioral detail beyond annotations: OAuth persistence requirement, phone verification for SMS, 10/day SMS cap, always-on feed access, and webhook signing. No contradiction with readOnlyHint=false or idempotentHint=true.

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 efficient, covering purpose, auth, types, and delivery channels in a single paragraph. It is appropriately sized, though bullet points could improve scannability.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is highly complete: it explains purpose, return value, auth, supported types, delivery channels, and access methods. No major gaps remain.

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

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

Even though schema coverage is 100%, the description enriches parameter semantics with concrete examples: items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE', and delivery constraints like verified phone and SMS cap. This adds real value beyond the schema.

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

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

The description states a specific verb + resource: 'Create a proactive monitoring subscription to a live-data event stream' and mentions the return of the subscription id. It clearly distinguishes this tool from siblings 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 context including the OAuth requirement, supported subscription types with examples, and delivery options. It implies alternatives by referencing recent_alerts for pulling existing alerts, but does not explicitly name when not to use this tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral context: it returns category-bucketed questions, each with the exact tool and argument shape, and is drawn from a live catalog of thousands of tools. This conveys that the output is dynamic and is a meta-tool, which is valuable for an agent selecting and invoking it.

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

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

The description is front-loaded with natural language example queries, then states the core purpose, output format, and usage options. Every sentence contributes value: the introductory queries capture intent, the body explains the tool, and the closing sentence provides explicit usage guidance. No unnecessary filler.

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

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

With no output schema, the description fully explains the return value (category-bucketed questions with exact tool call shapes). It also covers use cases, the optional parameter behavior, and how to start. Given the tool's complexity as an onboarding/meta-tool, the description is complete enough for an agent to know what it does and when to call 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?

The schema already provides 100% coverage for the `topic` parameter with a value list and description. The description adds extra meaning by explaining the behavior of omitting the parameter ('Call with no arguments for the full spread') and giving example topics ('finance', 'pharma', 'betting') beyond the schema's enum list. This goes beyond the baseline.

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

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

The description clearly states a specific purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer each. It distinguishes itself from sibling tools by framing itself as the first tool to use ('Use this FIRST') and by explicitly mentioning that it teaches how to call meta-tools like ask_pipeworx 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 gives an explicit when-to-use: '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 results. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses that ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This adds meaningful context about side effects and idempotency.

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, each carrying unique information: the action and the soft-delete consequence. No fluff, front-loaded with the core operation.

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

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

For a single-parameter tool with no output schema, the description covers the essential behavior: what it does, ownership, and what happens to the data. Combined with strong annotations and schema, it is fully complete.

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

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

The schema already fully describes the 'id' parameter as a subscription uuid returned by subscribe (100% coverage). The description merely repeats 'by id' without adding new format or semantics, so it stays at 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 'Cancel a subscription by id', using a specific verb and resource. It also clarifies the soft-delete behavior, distinguishing it from a hard delete and from sibling tools like subscribe or 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 implies when to use the tool (to cancel your own subscription) and provides a key constraint (ownership). It doesn't explicitly name alternatives or exclusion cases, but the guidance is clear enough for an agent to choose correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond that: the automated routing logic, the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found), the error structure, and the claim that it replaces 4–6 sequential calls. 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 every sentence earns its place. It opens with concrete invocation examples, then states the use case, then explains behavior, return values, and edge cases. It is information-dense without redundancy, and the structure naturally leads the reader from what and when to how and what to expect.

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 is exceptionally complete. It covers the entire pipeline, return verdicts with meanings, error handling (could_not_verify vs unsupported), and the fact that it consolidates multiple steps. The annotations and full schema coverage further round out the picture, leaving no critical gaps.

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

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

Schema description coverage is 100% (both 'claim' and 'tolerance_pct' have thorough descriptions, including examples and default behavior). The tool description itself does not add parameter-specific meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with specific verbs ('verify', 'fact check') and a well-defined scope. It also distinguishes between company-financial claims (via SEC EDGAR/XBRL) and other factual claims (via grounded pipeline), which helps differentiate it from siblings like deep_research or 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 explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the two sub-paths (financial vs. other claims). However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full when/when-not guidance.

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