Arcgis Glynncounty

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

Annotations already declare the operation safe (readOnlyHint, idempotentHint). The description adds valuable behavioral context beyond the annotations: the cost implication of BYO Anthropic key ('you pay Anthropic directly'), the pass-through behavior of `_apiKey`, and what a typical response contains. 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?

Two tightly structured sentences that front-load the core action, then cover defaults, optional configuration, return shape, and use cases. No filler or repetition—every clause earns its place.

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

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

With no output schema, the description compensates by enumerating the return fields (`{score, confidence, signals, raw_response}` plus combined view). It also provides use cases and parameter relationships. Minor gaps: no mention of rate limits, error cases, or explicit comparison with sibling tools, but overall it's sufficiently 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 coverage is 100%, giving a baseline of 3. The description adds meaningful semantics on top: it explains the relationship between `models` and `_apiKey` ('pass `_apiKey` to also probe Anthropic'), clarifies the default model, and notes billing expectations. This goes beyond the schema's individual parameter descriptions.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs') with a clear outcome ('score visibility (0-100) per model'), immediately distinguishing it from sibling tools. It clearly states what it does with concrete details like default model and per-model output.

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

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

The description provides clear context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains how to invoke different configurations (default vs. passing `_apiKey`). It stops short of naming alternatives or explicit exclusion criteria, but the guidance is strong.

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, non-destructive behavior. The description adds useful context beyond that, such as routing across 5,564 tools, argument filling, one-call execution, tier availability, and stable pipeworx:// citation URIs. It does not contradict the annotations.

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

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

The description is longer than average, but every section earns its place by providing routing behavior, domain examples, trigger phrases, and clear upgrade paths. It is front-loaded with the most important standing compare and ends with actionable alternatives.

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 provided, the description compensates by clearly explaining the return behavior: structured answers with stable citation URIs. It covers source scope, examples, defaults, upgrade alternatives, and special cases, making it complete for a router-style tool.

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

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

The input schema already fully documents the 'question' parameter and its aliases with 100% coverage. The description adds examples and natural-language usage patterns but does not need to add much, as the parameter is a simple free-text question.

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 scope: it routes questions to the correct tool among 5,564 tools across verified sources and returns structured answers with citations. It clearly distinguishes itself from web search and its siblings by naming ask_pipeworx_grounded and deep_research for different cases.

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 and step-up guidance, including 'PREFER OVER WEB SEARCH,' 'START HERE for most questions,' and exactly when to use ask_pipeworx_grounded or deep_research instead. It also clarifies that it handles news/breaking-data cases and covers many example domains.

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 include readOnly, openWorld, idempotent, and non-destructive flags. The description adds that it has candidate routing improvements (currently inactive) and mentions a fallback to nothing, though clarified. This provides moderate extra behavioral context without 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 repetitive, repeating 'exactly like ask_pipeworx' and 'no candidate is active' multiple times, and includes an irrelevant date '2026-07-26'. It could be significantly more concise.

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 purpose, usage, parameters, and behavioral context adequately for a router tool. No output schema is provided, so return value explanation is not needed. The contradictory 'Falls back to nothing' statement might cause confusion but is clarified in the next sentence.

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 includes six parameters all described as 'Alias for question', and the description explicitly states that query, q, prompt, text, input are aliases, fully clarifying their semantics beyond the minimal schema descriptions.

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

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

The description clearly states it is a universal router identical to ask_pipeworx with candidate routing improvements, and clarifies that currently no candidate is active so it exactly matches ask_pipeworx. This establishes its function and distinguishes it from the stable version.

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 clear guidance on when to choose this beta tool over the stable version. It also mentions candidate routing tests, providing usage context.

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

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

Even with annotations declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral detail: it extracts answers only from tool results, returns verbatim evidence and confidence, and explicitly enumerates refusal reasons such as not_in_source, no_tool_match, tool_error, data_truncated, and llm_error. This goes well beyond the annotations and helps the agent predict failure modes.

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

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

The description is long but every sentence earns its place: mode definition, routing/extraction behavior, return/refusal contract, use cases, and cost/alternative guidance. It is front-loaded with the core purpose and structured to build from behavior to practical usage. No filler or redundant restating of the tool name.

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 is comprehensive for a tool with no output schema: it explains return shapes, success fields, refusal reasons, and the extra cost. It also covers source grounding, evidence quoting, and high-stakes use cases. Given the complexity of routing across 5,564 tools and the potential for refusal, the description supplies enough context for reliable 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 the only substantive parameter (`question`) fully described as 'Your question in natural language' and aliases enumerated. The description does not add much beyond the schema; it clarifies high-level routing but no parameter-specific semantics. Baseline 3 is appropriate because the schema already carries the full load.

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

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

The description opens with a specific verb and scope: 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers from tool results rather than inventing facts. It clearly distinguishes from ask_pipeworx by noting same routing but extraction behavior, and from siblings by grounding to evidence. This is a precise, actionable purpose statement.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also provides a direct alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is model behavior for decision guidance.

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

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

The description discloses behaviors far beyond the annotations: it explains the resolver contract (market_match_confidence, scores, alternatives, suggestions), safety mechanisms (low-confidence short-circuit, closed-market blocking), wide-spread handling, and cancellation-rule risk. It also describes what happens on fallback and retry for news sources. This enriches the thin annotation set (readOnly/openWorld/idempotent/destructive) with critical operational details.

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, using uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) that make it scannable. While some details are dense, each section provides distinct value. It sacrifices brevity for completeness, but the structure earns a 4.

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

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

With no output schema, the description fully compensates by detailing the response shape (result.market, result.analysis, result.evidence), resolver contract, parent-event extractor, news fields, and safety behaviors. It covers edge cases like closed markets, wide spreads, and cancellation rules. For a tool with this complexity, the description is remarkably complete.

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

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

The input schema already has 100% coverage of the 3 parameters, each with clear descriptions. The main description adds context about input formats (slug/URL/question) and the include_raw trade-off, but these are largely mirrored in the schema. Since the schema does the heavy lifting, the description adds only marginal extra meaning, aligning with the baseline 3.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_edges or polymarket_arbitrage by focusing on per-bet data gathering and analysis. The use cases ('should I bet on X', 'what does the data say about Y') reinforce its 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 provides explicit use cases and examples, including classifier categories and fan-out examples for specific bet types. It does not explicitly mention when not to use this tool or name alternative siblings, but the clear context of 'use for...' statements gives strong usage guidance. Lacks exclusions, so a 4 rather than 5.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and the return format with pipeworx:// citation URIs. 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 dense yet well-structured: it starts with trigger phrases, then states the core function, and follows with per-type data details and output behavior. Every sentence contributes unique information, and the length is justified by the complexity.

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

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

Given there is no output schema, the description fully explains the return format (paired data + citation URIs), sorting behavior, and covers both entity types with specific data points. It provides enough information for an agent to select and invoke the tool correctly without ambiguity.

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?

Adds substantial meaning beyond the schema: explains what data is pulled for each type (10-K financials vs FAERS counts), provides example values, and notes fiscal year handling. The schema coverage is 100%, but the description enriches the semantics significantly.

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

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

The description explicitly states that the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, using example query patterns ('X vs Y'). It clearly distinguishes itself from sequential single-pack lookups, which differentiates 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?

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use type='company' vs type='drug' and mentions the inefficiency it replaces (8–15 sequential lookups), giving strong contextual direction.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the research process (decomposition, parallel tool routing), the nature of gaps[] (never invented), the second-hop iteration with depth variants, contradictions scan, and the resolvability of citations. It also warns about empty gaps for out-of-catalog topics. 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 each sentence conveys unique, valuable information (account, alternatives, process, gaps, timing, citations). It is well-structured with clear sections, though slightly verbose; the front-loaded account warning and key distinction are effective. The length is justified by the tool's complexity, so only a minor deduction.

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, the description covers all necessary aspects: purpose, usage context, limitations (breaking news), behavioral guarantees (gaps, holes), parameter semantics, timing expectations, and even the resolvability of citations. It lacks an output schema but explains the findings packet structure, making it complete for an agent to understand what to expect.

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

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

Schema coverage is 100% via descriptions for both question and depth, but the tool description adds significant depth semantics: quick=3 facets, standard adds gap-recovery and contradictions, thorough adds iterative lead-chasing. It clarifies the paid plan requirement for thorough, which is not in 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 explicitly states it performs grounded multi-source research across Pipeworx's structured data sources in a single call, and distinguishes itself from open-web search and sibling tools like ask_pipeworx. It also names specific use cases and alternatives, making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly states when to prefer ask_pipeworx (single lookup, breaking news). It also explains depth-level differences and account requirements, so the agent knows exactly when to select 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds meaningful behavioral context: results include full schemas with curated examples, are ready to call directly, and no second schema lookup is needed. This goes beyond the annotations and helps the agent anticipate the tool's output behavior.

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

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

The description is three sentences, front-loaded with the action, includes a compact list of domains, and ends with a clear directive ('Call this FIRST'). Every sentence earns its place with no redundant filler.

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

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

For a read-only discovery tool with strong annotations and full schema coverage, the description completely covers purpose, usage context, and return value (top-N tools with schemas). No output schema is needed, and the description fills the gap of what the agent receives.

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 reinforces that 'top-N' relates to limit and 'describing the data or task' relates to query, but it does not add new semantics beyond what the schema already provides. The schema fully documents aliases and defaults.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and lists many domains. This distinguishes it from sibling tools as a discovery/meta-tool.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it and hints at exclusions (when you already know the exact 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?

The description discloses several behaviors not covered by annotations: parallel fan-out across multiple sources, soft-fail for the USPTO PatentsView API sunset, fallback from GDELT to GNews, and the exact return fields including URIs. Annotations already indicate read-only/idempotent, but this adds critical operational 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 compact yet packed with actionable details: examples, usage instructions, fan-out sources, return structure, and limitations. It is well-organized and front-loaded with query phrasings, with no wasted words.

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

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

Given the number of integrated sources, fallbacks, and limitations, the description covers everything an agent needs: input constraints, expected outputs, source-specific behavior (e.g., 'patents soft-fail'), and a pointer to resolve_entity for unsupported inputs. The absence of an output schema is compensated by a detailed list of returned fields.

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 type and value parameters are fully described in the schema, including the zero-padded CIK format and ticker examples. The description repeats the same parameter details without adding new semantic meaning, so it stays at the baseline of 3.

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

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

The description explicitly states it produces a 'full cross-source profile of a US public company in ONE parallel call' with concrete query examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from siblings by naming resolve_entity for name-based lookups and positioning itself as the preferred holistic 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?

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'. This directly addresses alternatives and preconditions.

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

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

Annotations already indicate destructive and idempotent behavior (destructiveHint=true, idempotentHint=true). The description adds useful context about reasons for deletion and complements the memory workflow, but does not contradict annotations.

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

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

Two concise sentences communicate the action, usage conditions, and related tools without waste. The description is front-loaded and every sentence earns its place.

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

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

The tool has a simple signature (single required param), annotations cover safety/behavior, and the description provides sufficient context for when to use it. No output schema is needed, and the pairing note completes the mental model.

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% (key described as 'Memory key to delete'). The description mentions 'by key' but adds no new parameter details beyond what the schema already provides. 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 action ('Delete a previously stored memory by key') with a specific verb and resource. It also differentiates from sibling tools by mentioning 'Pair with remember and recall', making its role distinct.

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

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

Explicit usage conditions are given: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This clearly tells when to use the tool and provides context for alternatives.

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

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

The description goes beyond the annotations by disclosing the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a 'single text blob ready to drop at site-root/llms.txt.' This adds behavioral context consistent with the readOnly and idempotent hints.

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

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

The description is compact and well-structured. It opens with the primary action, then provides process, output format, and use cases in a clear sequence. Every sentence adds valuable information without fluff.

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

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

Given the tool's simplicity (2 params, no output schema, strong annotations), the description is remarkably complete. It covers purpose, process, output format, and concrete use cases, making it self-sufficient for an agent 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?

All parameters are fully described in the schema (100% coverage), so the baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it mentions 'any URL' and 'key links' but does not detail max_links or parameter usage.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It includes specific verbs and resources, and differentiates from sibling tools by focusing on generating llms.txt rather than checking or scanning AI presence.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not mention when not to use the tool or explicitly compare with alternatives like scan_competitor_ai_presence, 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds specific return contents (fields, geometry type, record count, capabilities), reinforcing the safe read-only behavior. However, it does not disclose error handling or URL format edge cases, though the schema example partially covers this.

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

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

The description is a single, dense sentence that immediately conveys the tool's purpose and output. No wasted words or redundant content.

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

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

With only one parameter, strong annotations, and a clear output description, the tool is simple enough that the description covers the essentials. It could optionally mention the URL format more explicitly, but the schema example covers that need.

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 the single 'url' parameter, with a type and example provided. The description does not add additional parameter semantics beyond what the schema already communicates, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource (ArcGIS Feature/Map Service layer's schema) and key output details (fields, geometry type, total record count, capabilities). This distinguishes it from sibling tools like query_layer, which likely query data rather than schema.

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?

No explicit when-to-use or alternatives are mentioned. The description implies usage for schema inspection before querying, but it does not contrast with query_layer or other related tools, leaving the agent to infer appropriate contexts.

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 reveal readOnly/idempotent/non-destructive. The description adds value by specifying return fields, the 'active' filter behavior, and caller scoping, which are not in annotations.

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

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

Three crisp sentences: purpose, return fields, usage guidance. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple read-only list tool with one optional param, the description covers purpose, usage, and return fields. It omits the include_inactive parameter mention, but the schema fills that gap. No output schema exists, so field listing is beneficial.

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

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

Schema coverage is 100% for the single optional parameter include_inactive. The description reinforces the 'active' default but doesn't explicitly explain the parameter or add syntax details. 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?

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like subscribe/unsubscribe by focusing on listing, and explicitly lists return fields.

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

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

Provides clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it, though it doesn't contrast with alternative tools or mention exclusions.

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

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

Annotations are all false and convey little, so the description carries the behavioral burden. It discloses rate-limiting (5 per identifier per day), the claim_token workflow for later lookup, that filing is free, that the team reads digests daily, and that feedback affects roadmap. This goes well beyond the structured data.

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

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

The description is dense and front-loaded, opening with the core purpose. It is longer than average but every sentence adds useful operational detail (scope, exclusions, workflow, limits). A slightly tighter structure would earn a 5, but this is well-organized for a nuanced feedback tool.

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

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

With no output schema, the description still informs the user what to expect: a claim_token upon filing, later status updates, and resolution details. It covers input semantics, exclusions, rate limits, and account-free operation—complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description enriches each parameter significantly. It explains how to use claim_token with "no other arguments," describes the optional context object as relating to tool/pack/vertical, specifies message content guidance, and defines the type enum's practical use. This exceeds schema descriptions.

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

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

The description opens with a clear verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It precisely frames the tool's scope as feedback about Pipeworx-provided tools and distinguishes it from sibling tools by explicitly stating it is ONLY for tools served by this Pipeworx connection.

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

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

Provides explicit when-to-use guidance: bug (wrong/stale data), feature, data_gap, and praise. Also gives a clear exclusion: if the tool came from a different MCP server, report it there instead, and offers a disambiguation rule: "Not sure? Pipeworx tool names are the ones this connection lists." This is exemplary 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 indicate read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window'. This exceeds annotations without contradicting them.

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

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

The description is longer but well-structured with numbered use cases and a clear main sentence. Every sentence adds value; no filler. It front-loads the core function and then provides contextual details.

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

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

Tool is simple (one optional param, no output schema), and the description fully covers output composition ('top tools, top packs, total call volume', 'just (pack, tool, count)'), data source, privacy, caching, and use cases. No gaps for a tool of this complexity.

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

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

Single parameter has 100% schema coverage with enum values and default. The description adds behavioral semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which enriches the schema's plain list. Baseline 3 plus added context warrants a 4.

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

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

The description states the tool 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)' with a specific verb and resource. It clearly distinguishes from sibling tools like discover_tools by focusing on aggregate trends rather than individual discovery.

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

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

The description provides explicit use cases: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice', and 'seeing whether your use case aligns with what most agents need'. It lacks explicit when-not-to-use or named alternatives, so not 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 indicate a safe read-only operation (readOnlyHint: true, destructiveHint: false), but the description adds substantial behavioral nuance. It discloses the fill-check mechanism, warning that realizable_edge_pp ≤ 0 means the edge is not tradable, and explains filtering rules like skipped_low_similarity and placeholder fraction. This goes well beyond the structured hints.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. While every sentence is informative, some redundancy exists, such as explaining event and topic modes in both the main text and the parameter details.

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

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

The description thoroughly explains input modes, output fields (opportunities[], partition_check, fill-check results), and edge-case behavior, compensating for the lack of an output schema. However, it does not explicitly describe the response shape for trending_scan (no-args) mode, and it remains ambiguous whether topic mode produces a partition_check, leaving minor gaps for a complex tool.

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

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

The input schema already has 100% description coverage for event and topic parameters, but the description enriches understanding by providing concrete examples (e.g., 'fed-decision-may-2026'), accepting full URLs, and explaining the no-args mode. This adds meaning beyond the schema's simple 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 states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb and resource, and distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by describing its unique analytical approach.

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for a specific market, and topic for cross-event scanning. It also provides a recommendation ('event (recommended for a specific market)') and points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), demonstrating clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: caching at KV level for 1h, edge calculation net of slippage, Kelly cap at 0.25, 24h-move warning, placeholder-slug filtering, and Fed bet caveats. This goes far beyond the annotations without contradicting them.

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

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

The description is extremely long and dense, with nested parentheses and ALL-CAPS section headers. While information-rich, it is not concise; an agent must parse a wall of text. The structure helps (labeled segments, knobs, response top-level), but it could be trimmed without losing essential 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?

With 9 parameters, no output schema, and no nested objects, the description must explain the response shape. It does: top-level by_segment, fed_candidates/fed_note, and _diagnostics. It also details per-opportunity fields and filter behaviors. This gives an agent everything needed to interpret results and configure calls.

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 already describes all 9 parameters. The description adds extra semantics beyond schema, such as explaining that min_partition_leg_kelly applies to best per-leg Kelly because partition arbs return parent-level kelly_fraction_half=0 by design, and framing min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS'. This adds 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings by detailing three model families and response segments, making the tool's purpose distinct from polymarket_arbitrage or polymarket_edge_tracker.

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

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

Provides a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains tradeable-edge knobs and filters, but does not explicitly name alternatives or state when not to use this tool versus sibling tools, so it falls just short of a 5.

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

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

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by exposing important behavioral traits: snapshots are only written on cache-miss so gaps mean no scan occurred, history is bounded by the 60-day TTL, decay is computed from daily closes (not intraday), and edge_pp_net sign convention (negative = SELL YES) is disclosed. This is substantive transparency that materially affects interpretation of results. No contradiction with annotations.

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

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

The description is long but well-structured into purpose, args, RESPONSE, and LIMITS sections, with the key question front-loaded. Every sentence carries substantive information, and the formatting makes scanning easy. It earns the length by packing in response-shape details and data caveats that are not otherwise available from schema or annotations.

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 enumerating the three response arrays (tracked, expired, snapshot_dates), key fields (first_seen, trend, decay_pp_per_day, lifespan_days), and the sign convention for edge_pp_net. It also explains critical context like snapshot gaps, TTL limits, and daily-close semantics, making the tool's outputs interpretable without any external schema. For a tool of this complexity, this is highly complete.

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

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

The schema already provides full descriptions for both parameters (100% coverage), including defaults and clamps, so this dimension starts at a strong baseline. The description adds useful semantic context by calling 'window' a 'snapshot family' and explaining how days/window affect which snapshots are read. It slightly repeats schema info but enriches it with framing about snapshot families and response 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 uses a specific verb ('answers') and names a clear resource: edge persistence/decay telemetry from daily polymarket_edges snapshots. It clearly distinguishes itself from the sibling polymarket_edges by focusing on time-series persistence and decay rather than fresh edges. The opening question and example ('fresh wide edge vs 3-week-old wide edge') sharpen the 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 clear context for when to use this tool: when you need to know how long an edge has existed and whether it is shrinking, and it warns that a long-standing wide edge is meaningfully different from a fresh one. It does not explicitly name an alternative tool to use for current edge values, but the sibling 'polymarket_edges' is implicitly contrasted by saying this is built from snapshots of it. Limitations like 'not intraday' further guide appropriate use.

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

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

While annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral detail beyond those flags: it walks the order-book ladder, returns specific metrics like top_of_book and slippage_pp, and warns about forced_directional_risk and thin_legs. It also explains the verdict categories and the risk of partial fills. 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 and dense, but every clause serves a purpose for a two-mode tool. It front-loads the core purpose and then systematically covers single-market, basket, and usage guidance. The main weakness is that it's a single wall of text with long sentences; bullet points or section breaks would improve skimmability. Still, it is efficient for the complexity it covers.

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 carry the burden of explaining return values, and it does: it enumerates the fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin books and partial fills. For a complex tool with 4 params and no output schema, this is 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 enriches every parameter. It explains how `market` vs `event` selects mode, how `side` defaults differ between modes, and how `size_usd` is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional per leg). It also mentions the default and clamp range, adding meaning well beyond the schema's property descriptions.

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

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

The description opens with a specific, outcome-oriented purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk, not signal generation. It also differentiates two modes (single-market vs basket), making the resource and action unambiguous.

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

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

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode that justifies its use (partial fills converting an arb into unhedged directional risk). This is far beyond vague context—it names the exact trigger conditions and 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?

With annotations already declaring read-only and idempotent hints, the description adds substantial behavioral context: it explains compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and warns that 'aligned:false means spreads are mathematically meaningless.' It also reveals that most pre-mapped topics currently return warnings, setting realistic expectations. 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 carries meaningful information or caveats. It is front-loaded with purpose, then modes, response fields, and safety fields. Some redundancy exists (topic shortcuts are enumerated in both the description and schema), and the all-caps 'SAFETY FIELDS' label is slightly noisy, but the density is justified for a complex tool.

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

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

With no output schema, the description explains the return fields in detail: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It also covers interpretation of warnings and edge cases (e.g., 'no arb exists,' 'events likely semantically unrelated'). This is highly complete for a cross-venue analysis tool.

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

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

Schema coverage is 100%, but the description adds relational meaning between parameters: the topic shortcut auto-fetches matching events, while explicit ticker/slug override the mapped side. It also enumerates the 10 topic values again and clarifies that explicit mode is for 'custom pairings.' This goes beyond the schema's individual property descriptions, though the topic list is redundant.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue pricing differences and explicitly discussing equivalence of bet shapes. The two modes (topic shortcuts vs explicit ticker/slug) are clearly stated.

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

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

The description provides clear context on when to use each mode (topic shortcuts vs explicit pairings), and includes explicit caveats: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It explains safety fields that signal non-equivalent bet shapes and temporal misalignment. However, it does not name alternative sibling tools for comparison, so it stops short of explicit 'use this instead of X' guidance.

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

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

Annotations already declare the safe read-only nature, and the description adds value by clarifying that attribute rows are returned and geometry can be included. The sampling idiom is useful behavioral context beyond the annotation hints.

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

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

Four concise, front-loaded sentences, each earning its place: purpose, parameter syntax, return type, and a practical usage tip. No redundant content.

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

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

With no output schema, the description adequately states the return shape ('attribute rows (and geometry)'). It provides enough context for an agent to select and invoke the tool, including the source workflow and a sample call, though it leaves pagination details to the schema.

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

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

The input schema covers all 6 parameters with detailed descriptions, so the baseline is 3. The description adds minimal extra semantics beyond restating SQL-like where, comma-separated out_fields, and sampling idiom, but does not supplement the schema meaningfully.

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

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

The description clearly states it queries an ArcGIS Feature/Map Service layer by URL, with a specific verb ('Query') and resource. It distinguishes itself from siblings like layer_info (metadata) and search_datasets (finding datasets) by focusing on row-level attribute 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 indicates the tool is used after search_datasets (URL source) and provides a concrete sampling pattern ('where=1=1' + 'out_fields=*'). It lacks explicit exclusions or alternative mentions, but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: scoping to the agent's identifier (anonymous IP, BYO key hash, account ID) and the relationship with remember/forget. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action, then the use case, then scoping and pairing. Every sentence adds value, with zero fluff or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers what it does, when to use it, the scoping behavior, and related tools, making it fully self-contained for an AI agent.

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

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

Schema coverage is 100%, and the schema already describes the key parameter as 'Memory key to retrieve (omit to list all keys)'. The description repeats this behavior but does not add new parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys'. This is a specific verb+resource combination that distinguishes it from sibling tools like remember (save) and forget (delete).

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 to use this tool to 'look up context the agent stored earlier... without re-deriving it from scratch', providing a clear use case. It also mentions pairing with remember and forget, but does not explicitly exclude other lookup alternatives. Overall, it offers clear context but lacks explicit when-not-to-use guidance.

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

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

Annotations declare readOnlyHint:true, yet the description instructs 'Set mark_read:true to flag returned events read,' which modifies persisted feed state. This is a direct contradiction, so per rubric score is 1.

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

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

Four sentences cover purpose, return format, filtering, side-effect, and alternative access with no filler. Front-loaded with action verb.

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-like tool with no output schema, the description covers return field names, filter semantics, the mark_read side effect, and alternative polling endpoint. It's sufficient for an agent to confidently invoke.

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

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

All 5 parameters are documented in the schema, so baseline is 3. The description adds extra meaning by explaining mark_read's effect on subsequent calls and giving a concrete type example ('sec_8k') and since format ('ISO timestamp').

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

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

The description opens with 'Pull fired events from your subscription feed,' naming the exact verb and resource. It further specifies the returned fields (source, citation_uri, raw event payload), making it distinct from sibling tools like recent_changes 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?

It states 'Polls work fine' and points to the same feed at the HTTP URL for scripts/dashboards, giving alternative access. However, it doesn't explicitly contrast with sibling MCP tools, so it earns a 4 rather than 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses fan-out to SEC, GDELT/GNews, and USPTO, including fallback and soft-fail behavior. It also describes the return structure (changes[], total_changes, citation URIs), providing transparency into external dependencies and response format.

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 well-organized, starting with example queries, then function, sources, parameters, and return. It is longer than minimal but every clause provides necessary detail for a complex multi-source tool. Slight verbosity prevents 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?

For a tool relying on multiple external APIs and no output schema, the description covers all critical aspects: sources, fallback logic, date formats, return fields, and an explicit alternative. It is fully self-contained and leaves no major ambiguity.

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

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

Schema covers all parameters (100% coverage), so baseline is 3. The description adds value by giving concrete formats and examples: `since` supports ISO or relative shorthand ('7d', '30d', '3m', '1y'), and suggests '30d or 1m' for typical monitoring. It also clarifies `value` can be a ticker or zero-padded CIK.

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 provides a change feed for a company over a time window, with specific verbs like "What's new" and "latest on". It explicitly distinguishes itself from entity_profile by contrasting dynamic changes with static profile 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?

Provides natural language example queries to signal when to use, and explicitly names an alternative: "Use entity_profile instead when you want the static profile...". It also explains fallback behavior (GDELT→GNews) and when each source is used.

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 (idempotent, non-destructive, non-read-only), the description discloses key behavioral traits: persistence scoping by identifier, retention differences for authenticated vs. anonymous sessions (24 hours), and the lifecycle pairing with recall/forget. These details are not present in the annotations and materially affect the agent's expectations.

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

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

The description is three sentences and front-loaded with the primary action ('Save data'), followed by usage context, storage semantics, and companion tools. Every sentence carries distinct, necessary information with no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage criteria, persistence behavior, scoping, and related operations. It is sufficiently complete for an agent to decide when and how to invoke the tool without needing additional context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds contextual examples (resolved ticker, target address) that align with the schema's examples but does not add new syntax or format details beyond what the schema provides. The 'scoped by your identifier' note adds a slight nuance to the key's meaning, but overall the description does not substantially augment 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+resource: 'Save data the agent will need to reuse later...' and differentiates from siblings by explicitly pairing with 'recall to retrieve later, forget to delete.' It also specifies the storage model ('key-value pair scoped by your identifier'), making the tool's function unambiguous.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also names the complementary alternatives recall and forget, and implies when not to use by contrast (i.e., when retrieval or deletion is the goal).

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, establishing safety. The description adds value by disclosing graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), internal cascading through multiple lookups, and explicit declaration of unresolved identifiers. This goes beyond the annotation metadata.

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 common query patterns and a clear directive. However, it is somewhat verbose in places (e.g., the long enumeration of identifier sources and behaviors), which could be tightened while retaining the same information. Still, every sentence earns its place.

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

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

For a tool with no output schema, the description thoroughly explains return values: for company, it lists identifiers (CIK, ticker, LEI with ownership, FIGI) and mentions source labelling and unresolved list. For drug, it specifies RxCUI, ingredient, brand, and citation URL. Graceful degradation and internal cascading are also covered, making the tool's behavior fully transparent.

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 clear type enum and value description, but the description adds substantial meaning: it explains how each type resolves (e.g., ISIN resolves to legal entity via GLEIF mapping, company accepts ticker/CIK/ISIN/name) and provides examples. This significantly enriches the parameter semantics beyond the schema alone.

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

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

The description clearly states it resolves user-spoken names to canonical/official identifiers, provides multiple concrete examples (ticker, CIK, LEI, RxCUI), and positions itself as the tool to use when you need an ID from a name. It distinguishes from sibling tools like entity_profile and compare_entities by specifying its role as the primary lookup bridge.

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

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

Explicit guidance 'Use FIRST whenever you have a name but need an ID' clearly establishes when to invoke this tool. It also describes supported entity types with detailed examples of what to expect. However, it does not explicitly state when NOT to use it or list alternatives for cases where the user already has a known identifier.

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 valuable behavioral context beyond this: it reveals that the tool probes each entity via ai_visibility_check, ranks results, and returns specific fields (score, confidence, signal density). This gives the agent a clear picture of the operation's mechanics and output, going beyond the annotations without contradicting them.

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

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

The description is concise and well-structured, with four sentences covering the core function, method, use case, and return format. It is front-loaded with the main purpose, and every sentence contributes necessary information without repetition. The example query makes it immediately actionable for an AI agent.

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), the description is remarkably complete. It explains what the tool does, how it does it (probing with ai_visibility_check), what it returns (ranked list details), and when to use it. The schema covers all parameter semantics, so the description focuses on behavior and context, making it sufficient for an agent to select and invoke the tool confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, particularly that the first entity in the array is treated as the 'subject' and the rest as competitors. This clarifies the expected input format and intent, providing extra value 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 clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), the resource (AI visibility), and the scope (multiple entities), which distinguishes it from the sibling ai_visibility_check (likely single-entity). The mention of 'ranks by score' and 'most/least recognized' further clarifies the 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 provides a clear use case ('competitive AI-marketing audits') and an example query, indicating when to use the tool. It also names the underlying probe tool (ai_visibility_check), which implies the alternative for single-entity checks. However, it does not explicitly state when not to use this tool or mention other alternatives like compare_entities, so it stops short of a perfect score.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. This discloses important runtime behavior and return conditions.

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

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

The description is dense but well-structured, front-loading the purpose and using lists to convey return fields, ecosystem limitations, and failure behavior. Every clause earns its place; there is no redundant or filler content.

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

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

With no output schema, the description thoroughly explains the return value: summary block fields, per-advisory detail, links, and recent versions. It also covers ecosystem scope, partial failure behavior, and timing caveats, making the tool fully understandable without need for additional context.

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

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

Schema description coverage is 100%, with clear descriptions for 'package' (scoped packages accepted) and 'version' (defaults to latest). The description does not add additional parameter semantics 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 clearly states the tool's purpose: a composite check for adding an npm package, fanning out to deps.dev and bundlephobia. It uses specific verbs ('scan') and resources ('dependency'), and distinguishes from potential package-related tools by noting NPM-only scope and pointing to deps.dev:version for other ecosystems.

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 when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative for non-NPM ecosystems (deps.dev:version directly), giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (read-only, open-world, idempotent, non-destructive). The description adds return-field details and a downstream usage note, but it doesn't disclose additional behavioral traits such as pagination, default limits, or any caveats about changing data. Some value over annotations, but not rich.

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

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

The description is two sentences with no filler. It front-loads the purpose, then lists return fields and a practical usage hint. Every sentence earns its place.

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

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

With no output schema, the description appropriately explains return values (name, summary, record_count, owner/org, url) and how to use the url with siblings. For a simple search tool, this covers the essential context, though it could mention default organization or sorting; the schema already handles limits.

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

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

The input schema covers all three parameters (query, limit, org_id) with full descriptions (100% coverage). The description adds no parameter-specific semantics beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Search' with a clear resource ('Glynn County GIS open geospatial datasets') and scope ('by keyword'). It also lists what is returned and how it connects to sibling tools like query_layer/layer_info, which distinguishes it from them.

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 contextual guidance by explaining the workflow: search datasets, then pass the returned Feature Service url to query_layer/layer_info. This indicates when to use this tool versus its downstream siblings, though it doesn't explicitly state exclusions or when not to use alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: returns top-N passages with offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, caps at 200K chars with truncation flagged, and allows verification of verbatim quotes. No contradiction exists.

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

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

The description is appropriately detailed but every sentence earns its place. It front-loads the core purpose, then explains use case, integration, and technical behavior. No filler. The structure flows logically from what → when → how.

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 moderate complexity (3 params, no output schema, but thorough annotations), the description is complete. It covers the input text origin, query format, limit behavior, output contents (passages, offsets, scores), technical mechanism, and integration with a sibling tool. No significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about the text being 'already pulled' and gives query examples, but these are illustrative rather than essential semantic additions. The schema already clearly defines all parameters, so the description provides marginal added value.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by focusing on searching within pre-fetched text and explicitly contrasts with ask_pipeworx_grounded for grounding over passages. The use case (record too big for prompt) is concrete and differentiates it from other search tools.

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

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

The description explicitly tells when to use the tool: 'Use when the record is too big to cram into the prompt.' It also explains the pairing with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages'), giving clear contextual guidance. It implies when not to use (when the text is small) and provides behavioral constraints (200K cap) that inform usage decisions.

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 auth needs, return value (subscription id), and delivery constraints such as sms verification and 10/day cap. This goes beyond the annotations (readOnlyHint=false, idempotentHint=true) by adding operational context for real-world use.

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 primary purpose, followed by requirements, type examples, and delivery details. Each sentence provides practical information without fluff, appropriate 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?

Most aspects are covered: purpose, requirements, return value, type examples, delivery options, and constraints. Omissions like webhook details and the other two types are filled by the schema's delivery and params descriptions, so the description is sufficient 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?

While the schema already documents params and delivery, the description adds richer semantics for three of five types (e.g., items:['5.02'] = officer change, cross-venue mispricings) and explains the sms/email delivery shorthand. This exceeds the baseline for 100% schema coverage.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with supported types and delivery channels. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on the creation action and providing concrete examples.

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 specifies the account requirement (OAuth, anonymous/BYO cannot persist), and notes that the always-on feed can be pulled via recent_alerts, implying an alternative to subscribing. This gives clear context, though it does not explicitly name when not to subscribe.

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 valuable behavioral detail: it returns category-bucketed example questions with the exact tool and argument shape, and describes the effect of the topic parameter. This goes beyond annotation-only coverage.

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

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

The description is slightly longer than necessary but is well-structured, moving from example queries to purpose to return details to usage instructions. Every sentence contributes value, including the note about the live catalog. The opening slash-separated list is a bit noisy but quickly conveys the user intent phrases.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, usage timing, parameter effects, and return value structure (category-bucketed example questions with tool+argument shapes). It also explicitly mentions related meta-tools, making it complete for an agent deciding whether 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?

Schema description coverage is 100%, and the parameter `topic` already has a full description with allowed values and omission guidance. The tool description repeats the same examples ('finance', 'pharma', 'betting') without adding new semantic meaning, 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 states a specific purpose: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It distinguishes from siblings by positioning itself as the 'FIRST' tool to use and references meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

Explicitly instructs '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 parameter usage (omit for full spread, pass topic to focus) and provides examples of topic values. This is clear when-to-use guidance with alternatives.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation semantics ('The row is deactivated (not deleted)'). This explains exactly how the non-destructive behavior (destructiveHint=false) is implemented and how it impacts historical data.

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

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

The description is two sentences long, front-loaded with the primary action, and every sentence contributes necessary 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?

The description covers the essential behaviors: cancellation, ownership, and the non-destructive nature with historical availability. However, it does not mention any return value or confirmation, which would be helpful given there is no output schema, but this is not critical for such a simple operation.

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

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

The input schema already describes the 'id' parameter fully as 'Subscription id (uuid) returned by subscribe.' The description adds no extra meaning beyond referring to 'by id,' so the baseline score of 3 applies due to 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 'Cancel a subscription by id,' which uses a specific verb (cancel) and resource (subscription) and clearly differentiates from sibling tools like subscribe and list_subscriptions. The scope is explicit and unambiguous.

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

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

The description provides clear context by stating the mechanism (by id) and constraints (ownership enforcement, deactivation not deletion). While it does not explicitly name alternatives, the deactivation note implicitly guides when to use this tool versus a permanent deletion 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?

Despite annotations already declaring readOnly/openWorld/idempotent hints, the description adds crucial behavioral nuance: it defines the six possible verdicts and explains the critical distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source covers it). It also discloses the two-path routing behavior and the tolerance_pct override semantics, which go well beyond the annotation hints.

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

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

The description is dense but well-structured: it opens with trigger phrases, then provides use context, routing details, output summary, critical caller warnings, and a comparison to sequential alternatives. It is longer than necessary, but every sentence carries useful information; the IMPORTANT for callers section is high-value and earns its place.

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

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

For a tool with no output schema, the description compensates thoroughly by listing the exact verdict values, describing the returned evidence (actual value with pipeworx:// citation and reasoning), and explaining error semantics. It covers the two technical paths, parameter behavior, and caller caveats, making it complete for an agent to invoke and interpret results correctly. The complexity of the tool justifies this level of detail.

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

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

Schema coverage is 100%, so the schema already documents both parameters clearly. The description adds extra meaning by explaining how tolerance_pct interacts with claim wording (overrides the implied tolerance, set 1–2 for hallucination detection, default capped at 5) and by giving concrete examples for the claim parameter, enriching the schema definitions with contextual guidance.

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

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

The description opens with concrete natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and states the tool performs natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools focused on search, research, and comparisons by describing a verify-and-judge pipeline with verdicts, and explicitly notes it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct' and provides a clear routing rule: company-financial claims go through the structured SEC EDGAR + XBRL path, while any other factual claim falls through to the grounded pipeline. It also names the specific alternative pattern it replaces, giving strong when-to-use/alternatives guidance.

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