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 signal read-only and non-destructive, and the description adds meaningful behavior: routing to one of 5,724 tools, filling arguments, returning structured answers with stable pipeworx:// citation URIs, one fast call, and working on every tier. 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 carefully structured: preference, supported domains, mechanism, trigger phrases, concrete examples, default guidance, and escalation paths. It is front-loaded with the most important routing instruction and each section serves a distinct purpose.

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

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

For a broad-routing tool with one required parameter and no output schema, this is highly complete: it explains supported data categories, expected input shape, citation output, when to use alternatives, and the breaking-news exception. An agent has enough context to call it correctly and route escalation.

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

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

Schema coverage is 100% and the schema already documents 'question' and aliases with examples, so the description does not need to repeat syntax. The description contributes use-case examples and question phrasing, but adds no new parameter-level meaning beyond the schema.

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

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

The description names a specific action (routes a natural-language question to the right one of 5,724 verified tools) and resource (Pipeworx), and immediately distinguishes itself from web search and sibling ask_pipeworx_grounded/deep_research. It clearly states the tool's role as the default factual-question entry point.

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

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

It gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and when-not-to-use directions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part fan-out. It also addresses the breaking-news edge case.

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

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

The description discloses non-obvious dynamic behavior: candidate routing improvements are 'enabled live whenever one is under test', no candidate is active right now, and this currently matches ask_pipeworx exactly. It also clarifies there is no fallback: 'this IS a full working router, just the experimental edge.' This goes beyond the readOnly/idempotent annotations and helps an agent anticipate changing behavior. No contradiction with annotations.

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

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

The description is reasonably concise and front-loaded with the beta identity and router scope. Each sentence adds useful context—current candidate status, usage instruction, and no-fallback reassurance. There is minor redundancy between 'identical universal router' and 'matches ask_pipeworx exactly,' but it doesn't obscure the meaning.

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

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

Annotations cover safety and idempotence, and the schema covers parameters, but there is no output schema. The description only promises 'same response shape' as ask_pipeworx without specifying what that shape is. For a universal router, more explicit detail about response format and routing behavior would round out the picture, though the alias relationship makes it invocable.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and their aliases well. The description adds only 'same arguments' without explaining question semantics, routing behavior, or expected phrasing. This meets the baseline but provides no additional parameter insight.

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 frames the tool as 'Beta version of ask_pipeworx: identical universal router (same 5,724 tools, same arguments, same response shape)', making it clear this is an experimental question-routing tool. It distinguishes itself from the stable sibling by its beta status, but the core 'ask a question and route it' action is implicit and relies on prior understanding of ask_pipeworx.

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 it exactly like ask_pipeworx when you want the newest routing', giving a clear condition for selection. It also explains the comparison role: 'results are compared against the stable router to decide what merges.' It doesn't state when not to use it, but the experimental/beta framing makes the exclusion inferable.

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

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

Annotations already establish read-only, idempotent behavior, but the description adds substantial non-obvious context: it refuses rather than guesses, returns verbatim evidence, and enumerates exact refusal reasons. It also discloses the performance/cost implication of an extra LLM call. No contradiction with annotations.

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

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

The description is information-dense but not bloated. Every segment earns its place: the mode label, routing mechanism, extraction rule, return contract, refusal reasons, use cases, and cost trade-off. It is front-loaded with the core differentiator.

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?

Even without an output schema, the description fully specifies both the success payload and the refusal payload, including possible refusal_reason values. It also covers scope, grounding behavior, and when to choose the sibling tool, leaving no critical operational gap.

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

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

Schema description coverage is 100%, and the schema already defines the question parameter and all aliases clearly. The description adds no parameter-specific semantics beyond the schema, so the baseline score of 3 applies.

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

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

The description states a specific mode — hallucination-resistant, grounded answering — and explains that it routes through the same machinery as ask_pipeworx but extracts answers only from tool results. It directly distinguishes itself from the sibling ask_pipeworx, making the tool's specialty clear.

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

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

Explicitly says to use this tool when answers will be quoted, cited, or acted on and when invention is unacceptable. It also gives a concrete exclusion rule: prefer ask_pipeworx for casual lookups because this tool costs an extra LLM call.

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

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

Annotations already declare readOnlyHint=true, 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?

Annotations already mark it read-only/idempotent, and the description adds far more: account gating, parallel decomposition across 5,724 tools, the findings-packet shape, gaps[] and contradictions[], second-hop recovery behavior, semantic excerpting, and latency expectations. It clearly sets expectations about when results will be empty ('never invented'). No contradiction with annotations is apparent.

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

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

The description is dense and front-loaded with the account requirement and the critical 'NOT open-web search' caveat. Each sentence delivers useful behavior, though there is some redundancy around ask_pipeworx routing and repeated mention of gaps[]/contradictions[]. It could be tightened modestly without losing signal.

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 enumerates the full response shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), clarifies citation resolvability, and covers timing and depth-specific behavior. For a complex research tool, this is unusually complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful depth semantics beyond the schema: it explains that 'standard' re-angles unanswered gaps, 'thorough' chases leads and requires a paid plan, and that natural-language multi-part questions are expected. This goes beyond simply restating the parameter names.

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

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

The description names the specific verb-resource pair (grounded multi-source research across Pipeworx's 1497 structured data sources), scopes it explicitly with 'this is NOT open-web search,' and distinguishes it from ask_pipeworx. It gives concrete examples of the broad/multi-part questions it is designed for.

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 versus when-not-to-use guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/colloquial news, and use ask_pipeworx if not signed in. It also states account/tier prerequisites and expected latency.

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?

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds substantial behavioral detail beyond that: the gross-vs-net fee disclosure, compatibility_codes semantics, the null meaning of temporal_alignment, and the rule that unknown legs are never paired. This goes well beyond what annotations alone 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 highly structured with labeled sections and front-loaded purpose. Almost every sentence carries unique information, though the density of safety-field explanation makes it heavier than strictly necessary for an agent to get started.

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

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

Since there is no output schema, the description carries the full burden of explaining response semantics, and it does so thoroughly: spread fields, compatibility codes, skipped-leg counters, temporal alignment null behavior, and fee limitations are all covered. An agent has enough context to call the tool and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is already strong. The description adds meaningful value by enumerating the topic shortcuts, explaining that explicit ticker/slug overrides the topic-mapped side, and giving concrete format examples for both 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 states a specific function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and clearly defines its scope and modes.

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

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

The description provides clear context for when the tool is relevant: when the same outcome is priced on both venues and bet shapes are equivalent, the spread is a real signal; it also explains the availability of pre-mapped topics versus explicit pairings. It does not explicitly name sibling alternatives or state when not to use this tool, but the operational guidance is sufficiently clear.

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

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

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?

Annotations already cover read-only/idempotent behavior, and the description adds substantial behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI unavailable, explicit `unresolved` reporting, ambiguous-name handling via `figi_candidates`, and ISIN-to-LEI mapping. This goes far beyond what annotations provide.

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

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

The description is information-dense and front-loaded with examples, but it is a long wall of text with deeply nested parentheticals, especially in the 'company' section. Breaking it into structured bullets or shorter sentences would improve scannability without losing content.

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

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

For a complex tool with no output schema, the description explains input constraints, supported entity types, identifier sources, ambiguity behavior, unresolved results, and fallback behavior. An agent has enough context to invoke it correctly and interpret what it returns.

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

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

Schema coverage is 100%, but the description still substantially enhances parameter meaning: it provides concrete input examples (AAPL, 0000320193, ozempic), explains enum semantics, and warns against passing full noun phrases like 'revenue bonds' because it breaks FIGI matching. This is valuable semantics beyond the schema.

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

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

The description uses specific verbs and resources: resolving user-spoken names into canonical identifiers for company and drug, with explicit identifier types (CIK, LEI, FIGI, RxCUI). It clearly differentiates itself from sibling tools by stating it is the first step whenever a name but no ID is available.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear conditions for use, and notes it replaces 2-3 manual lookups. However, it does not explicitly contrast with sibling tools like entity_profile or validate_claim, so exclusion conditions are left implicit.

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

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

Annotations already 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.