Arcgis Puyallup

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, covering safety. The description adds valuable behavioral context beyond this: cost implications ('you pay Anthropic directly'), default model choice, and the return structure with per-model fields. This goes beyond what annotations provide, though it does not detail rate limits or the meaning of 'signals'.

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

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

The description is three sentences, front-loaded with the core action, includes return format, configuration nuance, and use cases—all without redundancy. Every sentence adds value.

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

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

Despite having no output schema, the description explains the return format (per-model and combined view), usage scenarios, cost considerations, and parameter choices. It provides enough context for an agent to invoke the tool confidently and interpret results at a high level.

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

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

The input schema provides 100% parameter description coverage, so the baseline is 3. The description adds examples and confirms defaults (e.g., 'Default model is Workers AI Llama-3.3-70b (free)'), but these do not significantly change understanding of parameter semantics beyond what the schema already states.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx (asking questions) and scan_competitor_ai_presence (competitor focus), and explains both the action and the 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 explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains configuration choices (default model vs BYO key). However, it does not explicitly name alternatives or exclusion criteria, 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?

The annotations already declare read-only, open-world, and idempotent behavior, lowering the burden. The description adds useful context: the tool routes to a large toolset, fills arguments, returns citations, works on all tiers, and is fast. It does not disclose potential failure modes, but the added context is valuable and non-contradictory.

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

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

The description is long but every sentence earns its place. It is front-loaded with a key preference cue, then explains mechanics, usage triggers, examples, and escalation options in a logical structure. 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?

Given its role as a meta-tool with no output schema, the description covers the return format (structured answer with citations), domains, and use cases. It also explains how it differs from related tools. Minor gap: it doesn't discuss what happens if no tool matches the query, but overall it is highly complete for its complexity.

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

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

Schema coverage is 100% (all parameters are aliases for the single 'question' field), so the baseline is 3. The description reinforces the natural-language nature of the input with many examples, but adds no new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool's purpose: it routes questions to appropriate tools from a large set of verified sources and returns structured answers with citation URIs. It also positions itself as the default entry point and contrasts with sibling tools like ask_pipeworx_grounded and deep_research, which is strong differentiation.

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

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

Provides explicit guidance on when to use this tool over web search or sibling tools, including trigger phrases ('what is', 'look up', etc.), example questions, and escalation paths to ask_pipeworx_grounded and deep_research. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it is a beta with live candidate routing improvements when under test, currently none active, and it is a fully working router (not a stub). This explains the experimental nature and the equivalence to ask_pipeworx at the moment, which is rich and non-obvious information.

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 somewhat long but every sentence serves a purpose: defining the beta nature, explaining the routing experiment, clarifying current behavior, and giving usage guidance. It is front-loaded with 'Beta version of ask_pipeworx' and is structured logically. It could be trimmed slightly, but the detail is justified for an experimental tool.

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

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

Given the tool's complexity (beta relationship with a sibling, experimental routing, and no output schema), the description is remarkably complete. It covers the exact relationship to ask_pipeworx, the current state (no active candidate), the usage context, and even mentions the comparison process for merging improvements. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The description does not add extra parameter semantics beyond stating 'same arguments', but with full schema coverage the baseline of 3 is appropriate. The schema already explains the main parameter and aliases, so no further info is needed.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with the same universal routing capability. It states the tool's function (identical router, same 5,529 tools, same arguments, same response shape) and distinguishes it from the stable sibling by the experimental routing improvements. It could be more explicit about being a question-answering/router tool, but the 'universal router' phrasing conveys the core purpose.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the experimental context (results compared against the stable router) and the current state (no active candidate, so behavior matches ask_pipeworx). It does not explicitly name alternatives like ask_pipeworx_grounded, but the contrast with ask_pipeworx is clear enough.

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

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

The description discloses detailed behavior beyond annotations: the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), specific refusal reasons, and the guarantee that extraction uses ONLY the tool result. It also mentions the cost of one extra LLM call. Annotations only state readOnly/idempotent, so this is significant added 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 a single, dense paragraph. It is front-loaded with the key concept, and every sentence contributes value, covering purpose, behavior, use cases, and trade-offs. While a bit long, it is not wasteful and remains well-structured for the complexity it conveys.

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 absence of an output schema, the description thoroughly explains the return format and failure modes. It also covers the cost implication, usage context, and distinctions from siblings. The tool's complexity is high, and the description addresses all critical aspects needed for safe and correct 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% with all parameters being aliases for 'question' and each documented. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies. The one required parameter is clear from 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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly specifies the tool's function and differentiates it from the sibling ask_pipeworx. It explicitly states the same routing as ask_pipeworx but adds the grounded extraction behavior, making the purpose distinct and actionable.

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

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

Provides explicit usage criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and an explicit preference: 'prefer ask_pipeworx for casual lookups.' It also references the sibling tool ask_pipeworx and explains the trade-off (extra LLM call), 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?

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond by detailing resolver contract (match confidence, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread handling, cancellation-rule parsing, and news fallback behavior. No contradiction with annotations.

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

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

The description is very long and dense, with many sections (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). It is front-loaded with purpose and usage, but the sheer volume of detail (e.g., detailed news fallback fields, cancellation rules) makes it less concise. Each sentence is informative, but could be tightened.

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

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

For a complex tool with no output schema, the description is exceptionally complete. It explains the response structure, resolver matching, fan-out logic, safety short-circuits, edge cases (closed markets, wide spreads), and resolution-rule risk. This gives the agent everything needed to use and interpret the tool's output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter explanation beyond the schema—market input forms are already in property description, depth enum is explained, include_raw is documented. It mostly repeats schema content, though it provides helpful examples of fan-out tied to classifiers.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings (e.g., polymarket_edges, polymarket_arbitrage) by focusing on per-bet research with fan-out, and explains the input forms (slug, URL, question text).

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'—clear context. It also enumerates classifiers and fan-out examples. It does not explicitly mention when not to use or name alternative tools, but the context is strong enough to guide selection.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds significant behavioral context: it pulls from SEC EDGAR/XBRL for companies and FAERS for drugs, correctly handles off-calendar fiscal years (AAPL, NVDA), sorts results by the primary metric, and returns paired data with citation URIs. These details go well beyond the annotations and inform the agent about data provenance and output ordering.

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 about eight sentences, but every clause serves a purpose: trigger phrases, core function, preference directive, type-specific data details, sorting behavior, output format, and performance benefit. It is front-loaded with the most important usage cues and avoids repetition. The structure is logical, starting with user intents and proceeding to behavior and output.

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

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

For a tool with two entity types and multiple behaviors, the description is remarkably complete. It covers when to use, what data each type returns, fiscal-year handling, sorting, output format (paired data + citation URIs), and even notes it replaces many sequential lookups. The schema and annotations handle parameter constraints and safety, so the description leaves no significant gap for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for both parameters (type and values), so the baseline is 3. The description adds valuable meaning by specifying what data each enum value returns ('type="company" pulls LATEST 10-K revenue...', 'type="drug" pulls FAERS adverse-event counts...') and clarifies accepted input formats (tickers/CIKs vs names). This enriches the enum semantics beyond the schema's terse 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 clear trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and explicitly states the core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sibling tools by positioning as the preferred alternative to sequential single-pack lookups and mentions it replaces 8–15 lookups.

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 via example query patterns and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies the difference between type='company' and type='drug', helping the agent choose the correct variant based on the entities being compared. This provides clear usage context and an explicit alternative to avoid.

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

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

Annotations provide readOnly/openWorld/idempotent hints, and the description adds substantial context: account requirements, paid plan for 'thorough', latency expectations (15-60s, up to ~90s), guarantees about gaps[] ('never invented'), resolvable citations, semantic excerpting, and contradictions[] behavior. No contradiction with annotations is present.

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 information-dense, with every major section (account, alternatives, behavior, output, latency) earning its place. However, it is structured as a single stream-of-consciousness paragraph with multiple parentheticals and no section breaks, making it slightly harder to scan despite being front-loaded with the critical account requirement.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri semantics. It also addresses limitation scenarios (current-news topics returning empty gaps) and performance expectations, making it complete 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?

Schema description coverage is 100%, and the schema already explains depth enum values in detail (quick=3, standard=5, thorough=8, paid, gap-recovery). The description largely restates this information, adding only latency implications and a high-level mention of 'second-hop iteration' without introducing meaningfully new parameter semantics.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL'. It explicitly distinguishes itself from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups.

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

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

Provides explicit usage guidance with named alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states the fallback if not signed in: 'use ask_pipeworx instead — it works on every tier'.

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, but the description adds valuable behavior beyond those: it specifies the return payload ('names, descriptions, and full input schemas (with curated examples)') and that results are 'ready to call directly, no second schema lookup needed.' It also describes the ranking behavior ('top-N most relevant tools'). No contradiction with annotations.

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

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

The description is three well-structured sentences. It front-loads purpose, then gives concrete domain examples, then explains return format and usage priority. No redundant or filler content; 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?

There is no output schema, but the description explicitly describes the return value (tool names, descriptions, full input schemas, curated examples) and that results are directly callable. Combined with rich schema aliases and safety annotations, the description fully compensates for the lack of an output schema.

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

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

Schema description coverage is 100%, so the schema thoroughly documents all parameters including aliases and examples. The description adds little parameter-specific meaning beyond implying 'query' via 'describing the data or task' and 'top-N' via 'limit.' With high schema coverage, 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 states a specific verb+resource: 'Find tools by describing the data or task.' It enumerates many data domains (SEC filings, FDA drugs, etc.), and distinguishes the tool from siblings by positioning it as a meta-tool for discovery rather than direct data access. The 'Call this FIRST' note reinforces its unique role.

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

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

It explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and adds a strong priority cue: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context for selection among 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 readOnly and non-destructive. The description adds critical behavior: it fans out across multiple sources in parallel, returns specific fields (CIK, filings with URIs, fundamentals sorted by period_end DESC), and discloses that the patents API will sunset May 2025 and soft-fails. It also notes GDELT→GNews fallback, which is exactly the kind of context annotations can't convey.

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

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

Although the description is long, every sentence provides useful details—examples, output fields, failure modes, constraints. It front-loads examples but quickly moves to the core purpose. Slightly dense, but earned 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?

With no output schema, the description fully enumerates the return data (cik, filings, fundamentals, patents, news, LEI) and handles edge cases like unsupported names and patent API sunset. The tool's behavior is completely specified for an agent.

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

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

The input schema already covers both parameters with descriptions including examples and the name disclaimer. The description repeats this information without adding new syntax or format details. Baseline 3 is appropriate since schema coverage is 100%.

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 query examples and clearly states it produces 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from single-pack lookups and references resolve_entity for name disambiguation, making the tool's role unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing users to resolve_entity first. This gives clear when-to-use and alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and being a deletion operation, but doesn't disclose additional behavioral details like irreversibility or behavior for missing keys.

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: action, usage triggers, and related tools. No fluff, front-loaded with the core action. Every sentence earns its place.

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

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

For a simple single-parameter delete tool with annotations covering destructive behavior, the description is sufficient. It could mention what happens if the key doesn't exist or confirm permanence, but these are minor gaps given the simplicity.

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

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

The input schema fully describes the single parameter 'key' with 'Memory key to delete.' The description mentions 'by key' but adds no extra semantic beyond the schema, so 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 uses a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (create) and recall (retrieve).

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 context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, giving clear context, though it doesn't explicitly state when not to use it.

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

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

The description explains the internal process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and the output format ('single text blob ready to drop at site-root/llms.txt'), adding behavioral detail beyond the annotations' safety hints. It does not disclose potential errors or rate limits, but for a simple read-only tool this is sufficient.

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 concise sentences: purpose, process, and use cases. It is front-loaded with the core action, has no fluff, 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?

Given the tool's simplicity (2 params, no output schema), the description covers all necessary context: what it does, how it works, output format, and typical uses. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so both 'url' and 'max_links' already have descriptions. The description adds minimal extra parameter semantics (e.g., 'key links' aligns with max_links), but does not need to as the schema is complete. Baseline 3 applies.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with a specific verb, resource, and goal. It distinguishes itself from sibling tools by focusing on creating llms.txt files rather than auditing AI presence or visibility.

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

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

The description provides concrete use 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') but does not explicitly mention when not to use it or recommend alternative tools. This is clear context but lacks exclusions/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, and destructiveHint=false, so the safety profile is covered. The description adds the return contents (fields, geometry type, record count, capabilities), which is useful context beyond the annotations. However, it doesn't disclose potential behavioral aspects like performance implications of counting records or any URL format restrictions beyond the schema example.

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?

A single, front-loaded sentence delivers a complete thought without wasted words. It lists the key output elements succinctly and immediately states the tool's action and target.

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

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

With one parameter and no output schema, the description compensates well by enumerating the exact schema components returned (fields, geometry type, record count, capabilities). It is clear that the tool is for metadata rather than data queries. Minor omissions like error handling or authentication requirements are acceptable for a simple read-only tool.

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

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

Schema description coverage is 100% with a single parameter, and the schema already describes the URL format with an example. The description's mention of 'by url' is redundant. No additional parameter semantics are provided beyond what the schema offers, 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 begins with a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), then enumerates concrete return items: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer or search_within, which focus on querying 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?

The phrase 'by url' gives clear context that this tool is for retrieving layer schema from a URL. It does not explicitly state when not to use it or name alternatives, but the purpose is evident and distinct from sibling tools. This meets the 'clear context, no exclusions' bar.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds return field details and scoping to the caller's active subscriptions. This provides useful behavioral context not captured by 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?

Two concise sentences: the first states purpose and return fields, the second gives usage guidance. No filler or redundant information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. Everything an agent needs is present.

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

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

The only parameter (include_inactive) has a complete schema description. The tool description says 'active subscriptions', which aligns with the default behavior, but adds no additional parameter semantics beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on the read-only listing action.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it, though it doesn't name alternative tools directly.

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?

Given annotations are all false, the description carries the full burden and succeeds. It discloses the claim_token flow, rate limiting (5/day), daily digest reading, that it's free and doesn't count against quota, and the nuance about anonymous filing versus later claiming. This goes well beyond the minimal mutation/read signals 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?

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then flows logically through usage nuances, behavioral details, and operational constraints. 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 tool has 4 optional params, nested objects, and no output schema, so the description must cover all important behavior. It does: purpose, scope boundaries, claim_token return semantics, rate limit, and roadmap impact. It fully compensates for the lack of an output schema by explaining what to expect (claim_token and later status).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token workflow (filing returns a token, passing it later reads the reply), which is not fully captured in the schema parameter descriptions. It also clarifies the type enum implicitly and adds rate-limit context. However, it doesn't add deep syntax details for the context object, so a 4 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb + resource and distinguishes itself from sibling tools by scoping feedback to Pipeworx's own tools only, with explicit examples (bug, feature/data_gap, praise).

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

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

The description provides explicit when-to-use guidance (bug, feature/data_gap, praise) and explicit when-not-to-use guidance (if the tool came from a different MCP server), plus a fallback heuristic for identification. It names the exact conditions for filing, making alternatives clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it is self-aggregating, derived from CF analytics-engine, exposes no PII, only returns (pack, tool, count) tuples, and has varying cache durations (5min-1h). 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 rich but tightly organized, with a purpose statement, bulleted use cases, and a final note on data aggregation and caching. Every sentence adds information; there is no redundancy or filler, making it appropriately sized for the tool's simplicity.

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

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

The tool has only one optional parameter and fully covered annotations. The description supplies all necessary contextual details: return structure (top tools, top packs, total call volume), data privacy (no PII), derivation source, and caching behavior. Despite no output schema, the description adequately explains what the agent will receive.

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

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

The input schema fully documents the 'window' parameter with enum values and a basic description. The tool description goes further by explaining the semantic difference between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaningful interpretive 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 clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb (returns) and resource (trending signals from other AI agents), making it distinct from sibling tools like discover_tools or search_datasets.

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

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

The description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. This provides clear guidance on when to use the tool, though it does not mention alternatives by name.

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 an extensive set of behavioral details beyond the annotations: specific thresholds (3pp deviation, Jaccard ≥0.30, 20% placeholder fraction), placeholder slug filtering, the partition_check sum, and the fill_check against live CLOB depth with actionable guidance when realizable_edge_pp ≤ 0. This aligns completely with the readOnlyHint, openWorldHint, and idempotentHint annotations, adding significant value 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 long but tightly packed, front-loading the core purpose and usage before diving into technical details. Every sentence adds operational value—examples, thresholds, filters, and fill-check semantics—with no filler or redundancy. The length is justified by the tool's complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers how to invoke each mode, what filters apply, what output to expect (opportunities[], partition_check, fill_check fields), and when to use a sibling tool. It leaves no crucial operational gap for the agent.

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

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

Although the schema already covers both parameters (coverage 100%), the description enriches them with concrete examples for event ('fed-decision-may-2026') and topic ('Strait of Hormuz traffic returns to normal'), explains the internal machinery for each mode, and details the return signals (gap_pp, suggested_trade, partition_check), going far beyond basic schema descriptions.

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

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

The description opens with a precise verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates the tool from sibling tools by defining three operation modes (trending_scan, event, topic) and referencing the fill-check behavior, making it distinct from tools like polymarket_edges or polymarket_fill_risk.

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

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

It explicitly tells the agent when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event 'for a specific market' and topic 'for cross-event scanning', and closes by pointing to polymarket_fill_risk for custom sizing, providing an explicit alternative.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses caching ('Cached 1h at the KV level keyed on all knobs'), response segmentation, diagnostics, the 24h-move warning, and detailed model logic. It even warns about edge degradation and unreliable Fed signals. This goes far beyond annotation 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 a massive, dense block of text with nested clauses and many specific numbers (e.g., per-sport α values, gate thresholds). While every sentence carries information, it is not concise and would benefit from bullets or structured sub-paragraphs. Front-loading is okay but overall it is overwhelming.

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 details the response structure: by_segment, fed_candidates/fed_note, and _diagnostics. It explains why segments may be empty and how knobs affect results. Given the complexity of the tool (9 optional parameters), the description covers all essential behavioral and response aspects.

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 parameters are documented. The description adds cross-parameter rationale, e.g., that min_kelly will not filter partition arbs because they always return kelly_fraction_half=0, and that min_liquidity/max_spread_pp act as tradeable-edge gates. This contextual linkage is valuable 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 states the tool's purpose and differentiates it from siblings by mentioning the built-in model families and naming explicit outputs. It is not tautological and gives a concrete use case.

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

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

The description provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains why certain segments exist and how knobs control filtering. However, it does not explicitly name alternative tools for when-not-to-use, though the sibling list is present.

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 substantial behavioral context beyond the annotations, explaining response structure (tracked, expired, snapshot_dates), the meaning of 'trend' and 'decay_pp_per_day', and data limits (60-day TTL, daily closes vs intraday, snapshot gaps due to cache-miss). This enriches the agent's understanding of what the tool returns and its caveats, which are not covered by annotations.

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

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

The description is dense and fairly long, but every sentence contributes to explaining the tool's purpose, parameters, response format, and limits. It is structured with a clear opening statement, an 'Args:' section, a 'RESPONSE:' section, and a 'LIMITS:' section, making it scannable. It avoids fluff but could be more compact without losing meaning.

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

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

Given the lack of an output schema, the description is exceptionally thorough in documenting the response shape, field semantics, and edge cases (snapshot gaps, TTL, decay calculation basis). It also covers parameter defaults and limitations, making the tool fully comprehensible for invocation and interpretation 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?

The schema covers 100% of parameter descriptions, so the baseline is 3. The description essentially repeats the parameter information ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') but adds the 'snapshot family' concept and a 'max 30' nuance. This adds slight value beyond the schema but does not fully compensate or introduce new semantics beyond what's already present.

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: 'Edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges (which likely provides current edges) by focusing on historical persistence and decay. The verb 'telemetry' and the resource 'daily polymarket_edges snapshots' make the purpose unambiguous.

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

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

The description provides clear context for when to use the tool by specifying the exact question it answers: 'how long has this edge existed and is it shrinking?'. This implies when it's the right choice. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls short of complete exclusion guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context: it 'walks the ladder', returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and discloses failure modes like forced_directional_risk and stranding unhedged. This goes 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 long but highly structured, using capitalization (SINGLE-MARKET, BASKET) to separate modes and front-loading the purpose. Every sentence carries information, though it is dense and could potentially be tightened. The length is justified by the tool's complexity and the need to explain two modes and numerous return values.

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

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

Given the tool's complexity and the absence of an output schema, the description enumerates all return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) and explains behavior in both modes. It also covers edge cases like thin books and partial fills, making it a complete guide for an agent.

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

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

Although schema description coverage is 100%, the description adds significant meaning: 'size_usd (default 1000 — max spend on buys, target proceeds on sells)' and clarifies basket mode interpretation as 'settlement notional S (shares per leg; each share pays $1)'. It also explains the 'side' parameter in both modes, including the default auto-detection for baskets.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates between single-market and basket modes, and explicitly mentions sibling tools (polymarket_arbitrage, polymarket_edges) to distinguish its role as a pre-trade risk check.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states the two modes (market vs event) and explains why it matters, including the risk of partial basket fills converting an arb into an unhedged directional position.

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

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

Annotations already mark the tool readOnly, idempotent, and non-destructive, so the bar for additional transparency is lower. The description goes beyond annotations by detailing exactly when compatibility_warning fires (non-equivalent bet shapes vs unrelated events), what temporal_alignment means for spread validity, and what skipped_cross_type/subtype counters represent. It also candidly states that pre-mapped topics often yield no tradeable spread.

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

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

The description is front-loaded with the core purpose and then uses clear inline labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' to structure dense information. It is long but each sentence adds necessary caveats or behavioral detail; a more formatted list could improve scannability, but the text remains purposeful and not redundant.

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

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

There is no output schema, so the description correctly carries the burden of describing return values. It names the price format (raw probability 0-1), the key field top_spreads_pp with its sign convention (Kalshi − Polymarket), and explains all safety/caveat fields including matched_pairs, skipped_cross_type, and temporal_alignment. For a tool with this many edge cases, the description is exceptionally 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?

Input schema already covers all three parameters with descriptions, so baseline is 3. The tool description adds semantic value by explaining the two operational modes ('topic' vs explicit overrides), how the topic macro shortcuts auto-fetch events, and how overrides interact with the mapped side. This goes beyond the schema's per-parameter descriptions and clarifies the mental model.

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 opening line 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' names the exact resource and comparison being made. The tool is clearly distinguished from siblings like polymarket_arbitrage by specifying cross-venue spread over the same resolving question, and the description immediately establishes both the action (compute spread) and scope (Kalshi vs Polymarket).

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

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

The description clearly explains two usage modes: pre-mapped topic shortcuts or explicit ticker/slug overrides, and it cautions that most pre-mapped topics currently return compatibility warnings and are not tradeable. It does not explicitly name alternative sibling tools for comparison, so it stops short of a full when-to-use-this-vs-that explanation.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that it returns attribute rows and geometry, plus a sampling pattern. This is meaningful value beyond annotations, though it omits edge cases like max limit 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?

Two sentences, front-loaded with the action and resource, and zero wasted words. The sampling tip is immediately useful.

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 rich annotations, a fully described schema, and the description covering what, how, and a usage tip, this is complete for an AI 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. The description adds a quick synopsis of parameter roles and a concrete usage tip ('where="1=1" + out_fields="*"') that goes beyond the schema. This 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 opens with a specific verb ('Query'), identifies the resource ('ArcGIS Feature Service / Map Service layer'), and notes the url comes from search_datasets. It clearly distinguishes from siblings like layer_info (metadata) and search_within (spatial query).

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 ties usage to search_datasets, indicating when to use this tool. It also includes a practical sampling tip. However, it doesn't explicitly mention alternatives or exclusions, so it's 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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context about scoping ('Scoped to your identifier') and behavior ('omit the key argument' to list all). 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?

Two sentences, front-loaded with the verb and resource, and every clause adds useful information. No fluff or repetition of schema details.

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

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

For a simple retrieval tool with one optional parameter and strong annotations, the description is complete: it covers purpose, usage, scoping, and integration with sibling tools. No output schema exists, but the tool's return value is straightforward enough that not describing it explicitly is acceptable.

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 a clear description for 'key'. The description reinforces the schema by explaining the omit-to-list behavior and gives real-world examples of key values (ticker, address, notes), adding semantic richness beyond the schema.

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

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

The description clearly states the tool's action ('Retrieve a value previously saved via remember, or list all saved keys') and its resource (saved memory). It distinguishes itself from sibling tools by explicitly pairing with 'remember' and 'forget', making the retrieval role unambiguous.

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

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

It provides clear context on when to use ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and gives concrete examples. It doesn't explicitly state when not to use, but the tool's role as a memory lookup is well-defined relative to siblings.

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

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

The description discloses a behavioral trait that contradicts the annotations. The annotation readOnlyHint is true, but the description explicitly describes a state-changing action: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a mutation, directly contradicting the read-only hint. No credit can be given for transparency when the description itself undermines the annotation.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence adds useful detail. There is no redundancy or filler. It efficiently covers the return payload, filtering, mark_read behavior, and even notes an alternative access method.

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 many important aspects: what is returned, how to filter, mark_read semantics, and polling friendliness. However, it does not explicitly address the unread_only parameter or clarify the feed's retention/scope, and it contradicts the readOnlyHint annotation, creating overall incompleteness. The contradiction means the description cannot be fully trusted as a complete behavioral guide.

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

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

The schema already provides 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds value by explaining the effect of mark_read ('so the next call only shows newer ones') and giving an example for type ("sec_8k"). This goes beyond the schema's simple flag description, enhancing parameter understanding.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull), and the nature of the data (most recent alerts). It also distinguishes itself from siblings like list_subscriptions by focusing on the fired events feed.

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

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

The description provides clear usage context: it can be polled, filtered by type and since, and offers mark_read for read-tracking. It also mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like recent_changes or list_subscriptions, which would make the guidance more complete.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses substantial behavior: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO with a sunset note (PatentsView API sunset May 2025, soft-fails until reactivated). It also explains the return structure (changes[] grouped by source, total_changes, citation URIs) and the two accepted formats for `since`. No contradiction with annotations.

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

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

The description is dense but each sentence carries information: source fallbacks, sunset risk, parameter formats, return structure, and alternative tool. The opening quote list ("What's new with X" etc.) is a bit verbose but serves as an NLP-friendly utterance list for matching. It's longer than a simple two-sentence summary but earns its place given the tool's complexity.

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

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

Given there is no output schema, the description takes full responsibility for explaining the return format. It does so explicitly (changes[] grouped by source, total_changes, citation URIs). It also explains the multi-source behavior, fallback logic, and a soft-fail condition. With three required parameters and a complex backend, the description covers all necessary context for an agent to invoke the tool correctly.

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

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

The input schema already covers 100% of parameters with descriptions (type enum, since format, value as ticker/CIK). The description adds extra guidance: the '30d' or '1m' recommendation for typical monitoring, and clarifies that `since` can be ISO date or relative shorthand. This goes beyond the schema, though not dramatically, so a 4 is appropriate.

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

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

The description opens with concrete user intents ("What's new with X", "latest on Y") then states the tool's function: a change feed for a company in a date window, executed in one parallel call. It clearly identifies the resource (company) and the scope (time window), and distinguishes itself from the sibling entity_profile by explicitly directing users there for static profiles.

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

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

The description gives explicit usage direction: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." It also explains the underlying source fan-out and fallback behavior (GDELT preferred, GNews on rate-limit/5xx), which helps the agent decide when this tool is appropriate. This meets the 'explicit when/when-not/alternatives' bar.

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 (idempotent, non-destructive), the description adds key behavioral details: storage as key-value pairs scoped by identifier, retention policies (persistent for authenticated, 24 hours for anonymous), and the pairing with recall/forget. This significantly enriches the agent's understanding of side effects and state.

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

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

The description is three sentences, front-loaded with the core action, then usage guidance, and finally behavioral details. 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 two-parameter write tool with clear annotations and no output schema, the description is remarkably complete. It covers purpose, usage scenarios, persistence semantics, and related tools, giving the agent all context needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters, so the schema already fully documents key and value semantics. The description adds context about key-value scoping and examples, but these align with existing schema descriptions rather than adding new parameter-level information. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples like 'resolved ticker' and 'user preference'. It distinguishes from siblings by explicitly pairing with 'recall' and 'forget' tools, making it unambiguous which tool to use.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and lists concrete scenarios. Also clarifies persistence differences between authenticated and anonymous sessions, which helps the agent decide when this tool is appropriate.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses rich behavioral detail: graceful degradation if GLEIF/OpenFIGI is unavailable, internal cascading across endpoints, source labels on identifiers, and explicit handling of unresolved identifiers. This far exceeds what annotations provide and matches the tool's complexity.

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 sentence contributes: trigger examples, core purpose, supported types, output expectations, resilience behavior. It is front-loaded with examples and structured via 'SUPPORTED TYPES,' though a tighter format (e.g., bullets) could improve readability.

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

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

There is no output schema, so the description must explain return semantics. It does so comprehensively: for company it lists CIK, ticker, LEI, FIGI, ownership info, and unresolved handling; for drug it lists RxCUI, ingredient, brand, and citation. It also covers fallback behavior, making the tool's behavior fully predictable in context.

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

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

The schema already covers both parameters with 100% coverage, including input formats and examples. The description adds semantic depth by explaining what each type returns and how inputs map to outputs, but it overlaps with schema content for value. This is beyond the baseline 3, but not a full 5 since the schema already carries significant weight.

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

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

The description has a clear verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists trigger phrases and distinguishes from siblings by positioning itself as the first-step lookup tool. The supported types (company/drug) are well-defined.

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 guidance: 'Use FIRST whenever you have a name but need an ID,' supported by concrete example queries. It does not name alternative tools or when-not-to-use conditions, but the directive is strong and the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that it 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns a ranked list with specific fields. This discloses the internal workflow and output structure, going well beyond the annotations.

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

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

Three sentences, each with a distinct purpose: the primary action, the mechanism, and the use case. No redundancy. The description is front-loaded with the core purpose and remains compact.

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 explains the return format (ranked list with score, confidence, signal density), the relationship to the sibling 'ai_visibility_check', and the intended use case. With no output schema, this compensates effectively. The schema covers all parameters with clear descriptions, and annotations cover safety. It is complete for its complexity.

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

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

Schema description coverage is 100% with well-documented parameters (e.g., 'Array of 2-8 entities', 'First entry treated as the subject'). The description itself does not add parameter-specific semantics beyond what the schema already 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 states a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and distinguishes itself from the sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking. It also clearly states the output (ranked list with score, confidence, signal density).

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 says 'Useful for competitive AI-marketing audits' and gives an example question ('does Claude know about us as well as our competitors?'), which clearly implies when to use it for multi-entity comparison. It does not explicitly contrast with alternatives like 'ai_visibility_check' for single-entity checks, but the context is clear and the sibling list makes the distinction obvious.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses composite fan-out behavior, partial failure degradation, a specific 5-30s timeout for bundlephobia, and the 'sources_failed' field. This adds substantial behavioral context without contradicting annotations.

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

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

The description is dense but well-structured, starting with the core value proposition, then usage triggers, return format, and limitations. Each sentence serves a purpose, though it is longer than average; still, it earns its place for a composite 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?

Even without an output schema, the description enumerates all return fields, notes partial failure behavior, ecosystem restrictions, and performance caveats. This makes the tool's behavior fully predictable for an agent.

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

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

Schema coverage is 100% for both parameters (package and version), so the schema already provides full descriptions. The tool description does not add parameter-specific meaning beyond what's already in the schema, landing at 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 clearly states the composite purpose: a 'should I add this npm package' check aggregating deps.dev and bundlephobia. It names specific data sources and return fields, distinguishing it from any sibling tools. The verb 'scan' and resource 'dependency' are specific.

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

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

Explicit trigger phrases are given ('is X safe / popular / small', 'what does adding lodash cost me'). It also states the NPM-only scope and directs other ecosystems to 'deps.dev:version directly', providing clear when-not/alternative guidance.

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

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

Annotations already declare the tool as read-only, open-world, and idempotent, so the description need not repeat safety behavior. The description adds meaningful behavioral context by enumerating exactly what is returned (name, summary, record_count, owner/org, and Feature Service URL) and how the URL should be used downstream. This goes beyond what annotations provide, though it does not discuss rate limits or error 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 only two sentences, yet it packs in the tool's purpose, scope, return values, and downstream usage. It is front-loaded with a specific verb and resource, and every word contributes value with no redundancy or filler.

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

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

Given the tool has no output schema, the description adequately carries the burden of explaining return values by listing the exact fields. It also provides practical guidance on how to continue the workflow (passing the URL to query_layer/layer_info). With only three optional parameters and no nested objects, this description fully covers the essential context an agent needs to select and invoke the 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 covers 100% of parameters with clear descriptions (e.g., 'Keyword(s)', 'Max datasets', 'Optional ArcGIS orgId'). The description reinforces the 'keyword' aspect but does not add new meaning beyond schema. In accordance with the rubric, high schema coverage establishes a baseline of 3, and no additional parameter semantics are provided here.

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 ('Search'), the resource ('City of Puyallup GIS open geospatial datasets'), and the scope ('parcels, zoning, public works & city services'). It also distinguishes itself from sibling tools by specifying that the returned URL can be used with query_layer/layer_info, making its purpose and relationship to other tools explicit.

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

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

The description gives clear context for when to use this tool: to search for datasets by keyword and obtain their metadata. It provides an explicit pointer to downstream tools ('pass that url to query_layer / layer_info'), implying when those tools should be used instead. However, it does not explicitly state when not to use this tool or name alternative search tools, so it lacks formal exclusions.

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

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

The description discloses rich behavioral details beyond the readOnly annotations: returns char offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and has a 200K char truncation cap with a flag. No contradiction with the provided annotations; it fully describes the operational behavior.

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

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

The description is compact yet information-dense: three sentences covering core purpose, usage context, output composition, algorithm, and edge-case handling. Every sentence contributes value with no filler, and the opening immediately anchors the tool's function.

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

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

Despite no output schema, the description fully explains what the agent can expect: top-N passages with offsets and similarity scores. It also covers the input constraints (200K char cap), the technical approach, and the integration pattern with a sibling tool. The description is self-sufficient for correct invocation and result interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for each parameter: 'text' is clarified as already-pulled content, 'query' gets concrete examples, and 'limit' maps to the 'top-N passages' concept. This enriches understanding beyond the schema's bare descriptions, earning a 4.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb-plus-resource phrasing that clearly distinguishes this tool from siblings like search_datasets or ask_pipeworx. It also explains the exact use case (searching within already-fetched text) and pairs it with ask_pipeworx_grounded, making the tool's niche explicit.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also provides a clear workflow alternative: pairs with ask_pipeworx_grounded, suggesting ground over relevant passages instead of the whole document. This gives the agent actionable selection criteria relative to siblings.

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

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

Annotations already establish write semantics (readOnlyHint=false), but the description adds crucial operational details: OAuth account requirement, always-on feed, optional email/SMS with phone verification and a 10/day cap, webhook HMAC signing with a one-time secret, and auto-disable after 10 failed runs. This far exceeds what annotations convey, with no contradiction.

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

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

The description is dense but organized: main action first, then constraints, then type-specific examples and delivery semantics. While it is long, every clause contributes; there is no filler. The inline examples make it slightly harder to parse, but the structure is efficient 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?

Despite no output schema, it states the return value (new subscription id). It covers auth requirements, all subscription types, delivery channels with concrete limits, and failure behavior. For a 3-param tool with nested objects, this is comprehensive.

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 has detailed descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds practical enrichment: per-type examples, phone verification requirement, delivery channel behavior, and webhook security. This is valuable but some details are duplicated from the schema, so a 4 captures the added value without overstating.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It clearly differentiates from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and return value. The supported types and delivery channels further establish a distinct identity.

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: requires a Pipeworx OAuth account, explicitly notes anonymous/BYO accounts cannot persist subscriptions, and enumerates supported event types with examples. It does not explicitly name alternative tools for when not to use it, but the prerequisites and delivery constraints give strong usage direction.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds behavioral context about return structure (category-bucketed example questions with tool + argument shape drawn from the live catalog) and argument variability (no args vs topic). This exceeds the safety-only info from annotations, but doesn't describe output schema details or edge cases.

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 somewhat long but well-structured, front-loading with user utterances that signal purpose, then explaining behavior, usage, and positioning. Every sentence contributes; no filler. It could be tightened but is appropriately detailed for a complex tool with an optional filter.

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 tool with one optional parameter and no output schema, the description fully covers the return value (category-bucketed examples), the parameter semantics, and the intended usage context (first stop after connecting). It also addresses the common 'what data do you have?' question. Complete enough to invoke correctly.

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

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

Schema covers the single optional `topic` parameter with full enum description, so baseline is 3. The description adds examples ('finance', 'pharma', 'betting') and clarifies that omitting returns a cross-category spread, but this largely restates schema info. Little additional semantic value beyond schema.

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

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

The description clearly states this is the 'onboarding entry point' for suggesting what questions to ask Pipeworx, with a verb-object-resource structure. It distinguishes itself from sibling tools by positioning as 'Use this FIRST' and explicitly references meta-tools it teaches (ask_pipeworx, entity_profile, 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?

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter behavior ('Call with no arguments for the full spread, or pass topic to focus'). While it doesn't state explicit 'when not', the 'FIRST' instruction and alternative meta-tool names give clear context.

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

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

Beyond annotations, the description discloses critical behavior: ownership enforcement and soft-delete semantics ('deactivated, not deleted'), plus a pointer to where historical events remain visible. This adds meaningful context that annotations alone do not convey.

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

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

Two sentences, front-loaded with the primary action, followed by essential behavioral details. No extraneous words.

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

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

For a single-parameter tool with rich annotations and clear sibling context, the description fully covers what the agent needs: how to use it, constraints, and side effects. No output schema exists, but the description doesn't need to elaborate return values.

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

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

The input schema already provides 100% coverage for the single parameter, including its type and origin ('returned by subscribe'). The description doesn't need to add more; 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 uses a specific verb ('Cancel') and resource ('subscription by id'), immediately distinguishing it from siblings like subscribe and list_subscriptions. It clearly states the action's scope and effect.

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: use it to cancel a subscription by id, ownership is enforced, and deactivation preserves history. It doesn't explicitly name alternatives or when-not-to-use, but points to recent_alerts for historical events, providing enough guidance.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds significant behavioral context beyond those: it explains the verdict enum, clarifies the crucial distinction between 'could_not_verify' (check failed) and 'unsupported' (no source), and describes the dual pipeline (SEC EDGAR/XBRL vs. grounded). This is transparent, actionable guidance that annotations alone don't provide.

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

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

The description is longer than typical but every sentence contributes (triggers, routing, verdicts, error semantics, efficiency). It could be more front-loaded with a one-line summary instead of starting with example phrasings, but it remains readable and avoids 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?

Without an output schema, the description fully explains return values (verdict options, citation, reasoning) and error cases (could_not_verify vs unsupported). It also covers the two routing paths and the tool's efficiency advantage over sequential calls, making it self-sufficient for an agent to understand usage without external examples.

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

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

Even though schema coverage is 100%, the description adds extra meaning for tolerance_pct: explains it overrides the claim's implied tolerance, recommends values for hallucination detection (1-2), and notes the default cap of 5. It also clarifies how the claim parameter is used. This goes beyond the schema descriptions.

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

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

The description states a specific verb ('validate', 'fact check', 'verify') and resource ('claim'), and clearly differentiates from general Q&A tools by focusing on natural-language claim verification against authoritative sources. It also provides example phrasings and distinguishes itself from siblings like ask_pipeworx by noting it replaces multi-step 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 details the routing for company-financial claims vs. other claims. It lacks explicit 'when not to use' or direct alternative names, but the context is clear enough for an agent to select this tool over general Q&A tools.

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