Noaa Swpc

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond those hints: the default model is free, Anthropic requires a BYO key, and 'you pay Anthropic directly for those calls' – a cost-related behavior not captured in annotations. It also discloses the return shape, which is helpful.

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 main action, then key details (default model, cost, return format), then use cases. Every sentence earns its place; there is no redundancy or fluff. It is clear and skimmable.

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

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

Despite having no output schema, the description enumerates the return fields ('per-model {score, confidence, signals, raw_response} + a combined view'), covers prerequisites (API key for Anthropic), and mentions practical contexts (audits, pre-launch, monitoring). It is complete for a read-only probing tool with 4 parameters.

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% – every parameter (entity, models, _apiKey, context) has a descriptive schema. The description reinforces the default model behavior and the _apiKey requirement, but adds little that isn't already in the schema. It meets the baseline for well-documented parameters without significantly enriching them.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly defines the tool's core function and output, distinguishing it from generic search or analysis tools. The mention of per-model scoring and defaults adds precision beyond the title alone.

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 notes when an API key is needed ('pass `_apiKey` to also probe Anthropic') and the default model. No alternative tools are named, but the context is clear enough to guide appropriate use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds context about the domain (SWPC) and the inclusion of warnings, but does not describe return format, pagination, or what 'current' means (e.g., active alerts at this moment vs. a recent time window). 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 a single, front-loaded phrase with no filler. It efficiently conveys the tool's purpose in four words, earning its place without redundancy.

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

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

For a zero-parameter tool with an output schema and strong annotations, the description is mostly sufficient. It clearly states the resource and the fact that it provides current data. However, it could be slightly more explicit about what 'current' means (e.g., a snapshot of active alerts) and how it relates to 'recent_alerts' to fully complete the picture.

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 tool has zero parameters, so the baseline is 4. There is no parameter semantics to explain; the description need not compensate for any schema gaps, as the schema is empty and 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 clearly identifies the resource (SWPC alerts/warnings) and implies a read-only retrieval action. It implicitly distinguishes from the sibling 'recent_alerts' through the word 'current', but lacks an explicit verb such as 'retrieve' or 'list'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'recent_alerts'. The word 'current' hints at a time-scoped use case, but the description does not state when to choose this tool instead of others, nor does it mention any prerequisites or exclusions.

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

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

Annotations already declare readOnly/OpenWorld/idempotent, and the description adds routing behavior, argument filling, and citation URI output. No contradiction; useful context about being fast and universally available on all tiers.

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

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

The description is lengthy but information-dense; the opening directive 'PREFER OVER WEB SEARCH' front-loads the key takeaway. Every major sentence contributes distinct guidance, though it could be trimmed with bullet points.

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

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

Given no output schema and high task complexity, the description effectively covers return value (structured answer with citations), routing scope, and alternatives. It leaves minimal ambiguity about how to 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?

Schema covers 100% with aliases and a description for 'question.' The description's examples repeat schema examples and add practical query phrasings, but no additional parameter semantics beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx as a routing/aggregation tool for factual queries, with 'PREFER OVER WEB SEARCH' and explicit mention of routing to 5,462 tools across 1,419 verified sources. It distinguishes itself from ask_pipeworx_grounded and deep_research by naming specific use cases.

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

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

Explicitly tells agents to use this as the default entry point ('START HERE') and explains when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. It also notes that breaking news is already covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description's job is lighter. It adds valuable behavioral context: the beta nature, candidate routing improvements being enabled live during tests, the current match with ask_pipeworx, and the experimental edge. It does not contradict annotations. A slight gap is the lack of detail on potential behavioral differences when a candidate is active, but the description sufficiently discloses the 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 purpose (beta of ask_pipeworx), then current state, usage guidance, and a clarifying note about being a full router. Every sentence adds value, with no fluff or repetition of schema/annotations.

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

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

Given the tool's complexity (a universal router), the description is remarkably complete: it explains what the tool is, its current parity with the stable version, how to use it, and how results are evaluated. Although there is no output schema, the description states 'same response shape' as ask_pipeworx, which resolves the return format ambiguity. The description fully covers the operational context needed 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 covers 100% of parameters, including descriptions of all six aliases for 'question'. The description adds no parameter-specific semantics; it only references 'same arguments' in a general sense. Since the schema fully documents the parameters, the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx by highlighting the experimental routing improvements and the fact that it currently matches ask_pipeworx exactly, making it distinguishable from siblings.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells when to use it and contrasts with the stable alternative. It also clarifies that it is a fully functional router, not a fallback, addressing potential misuse.

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 this as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral detail: the exact success and refusal response structures, the refusal reasons list, the 'only what the tool result contains' grounding constraint, and the extra LLM call cost. While auth and rate limits are not mentioned, the description provides more than enough transparency beyond annotations.

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

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

The description is a dense, front-loaded paragraph with no wasted words. Every sentence contributes: purpose, mechanism, return types, usage scenarios, and cost trade-off. It's concise yet fully informative.

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 (routing across thousands of tools, refusal logic) and lack of an output schema, the description covers the essential return values and behavior thoroughly. It also contextualizes against the sibling ask_pipeworx. Minor omissions like specific refusal trigger conditions or evidence formatting don't undermine overall completeness.

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

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

Schema description coverage is 100% — each of the six parameters has a clear alias description. The description itself adds no parameter-specific semantics beyond what the schema already states. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant, grounded answer mode for high-stakes reads. It distinguishes from siblings by contrasting with ask_pipeworx and noting the extra LLM call. The verb 'extracts' and the specific routing mechanism make the function unambiguous.

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

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

The description explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains (financial, legal, medical, public statements). It also provides an alternative: 'prefer ask_pipeworx for casual lookups.' This is clear, practical guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the '30-min' time resolution and 'ovation' model type, which is useful context, but it does not describe the output format or any limitations. It is consistent with annotations, with no contradictions.

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

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

The description is a single short phrase, highly concise. It conveys the essential purpose without waste. However, it is slightly under-specified, as it could mention that it returns a forecast or includes details about the ovation model, but for a zero-parameter tool this level of brevity is acceptable.

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 simplicity of the tool (no parameters, presence of an output schema), the description is largely complete. The output schema covers return value details, and the description states the subject and time frame. It is slightly lacking in usage context, but the overall context is adequate.

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 tool has zero parameters, so the baseline per rubric is 4. The description does not need to add parameter information, and the schema confirms no parameters exist, which is sufficient.

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

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

The description clearly identifies the tool as providing a 30-minute aurora forecast. It uses a specific noun phrase 'ovation aurora forecast' which indicates a specific model and time horizon. However, it does not explicitly distinguish it from sibling tools like 'forecast_text' or 'kp_index', though the term 'aurora' is more 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?

There is no guidance on when to use this tool versus alternatives. Given the many sibling tools related to space weather and forecasts, the description provides no context for selecting this tool over others.

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

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

Annotations declare readOnlyHint/openWorldHint/idempotentHint, but the description goes far beyond that. It discloses parallel fan-out, resolver confidence behavior, low-confidence short-circuiting with status:"low_confidence_match", closed-market handling, news fallback flags (_fallback_attempted), wide-spread illiquidity warnings, and cancellation-rule risk. These are rich behavioral traits not captured 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 long but well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded purpose. Each section adds essential operational detail, yet some phrasing (e.g., the 'audited arb-bot ledgers' anecdote) is narrative rather than strictly directive. It is information-dense but could be trimmed slightly without losing value.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous dynamic behaviors), the description is exceptionally complete. It covers input resolution, classifers, fan-out paths, response field semantics, resolver matching logic, parent-event extraction, news fallbacks, safety short-circuits, closing market behavior, and cancellation-rule risk. This fully equips an agent to understand what will happen and how to interpret results, compensating for the absence 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 coverage is 100%: all three parameters (market, depth, include_raw) have descriptions in the schema. The description does not add substantive parameter-level meaning; it restates that 'market' can be a slug/URL/question and mentions depth's default in schema. The `include_raw` recommendation ('When false (recommended)...') appears in the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description opens with a specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the input types and use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on evidence gathering rather than pure market metrics.

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

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

The description explicitly states when to use the tool with three example query patterns and even shows classifier and fan-out examples. It does not, however, explicitly name alternative tools for exclusion or contrast with siblings, so it stops short of the full 'when not to use' guidance. The context is clear but 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is well-covered. The description adds only 'real-time' as a behavioral trait, which is a minor addition; it does not explain update frequency, latency, or data provenance. This adds some value but not substantial context beyond annotations.

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

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

The description is a single short phrase 'Boulder K-index real-time', which is highly concise and front-loaded with the key term 'Boulder K-index'. It avoids filler, but is more of a label than a complete sentence. It is not overlong, yet it could be slightly more descriptive without harming conciseness.

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

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

The description is extremely thin and fails to explain what Boulder K-index is, how it relates to the planetary Kp index, or when to use this tool over the sibling 'kp_index'. Even though the tool is simple and an output schema exists, the lack of any differentiation from similar tools makes the description incomplete for agent selection.

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 tool has zero parameters and the input schema is empty, so there is no parameter ambiguity. The schema coverage is trivially 100%, and the description need not add parameter details. This is the ideal scenario for parameter semantics, as there is nothing to explain or compensate for.

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 'Boulder K-index real-time' clearly identifies the resource (Boulder K-index) and temporal scope (real-time), which distinguishes it from the sibling 'kp_index' by location. However, it lacks an explicit action verb like 'get' or 'retrieve', making it a noun phrase rather than a full tool description, and the distinction from similar siblings is implicit.

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 no guidance on when to use this tool vs. alternatives such as 'kp_index', 'solar_wind', or 'aurora_forecast'. There is no mention of use cases, prerequisites, or situations where one should prefer this tool over others, leaving the agent without selection criteria.

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

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

Beyond annotations, the description reveals key behaviors: pulls SEC EDGAR/XBRL data, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. This level of detail far exceeds what annotations provide.

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

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

The description is dense but every sentence contributes unique, actionable information—from trigger phrases to data sources to sorting behavior. It is front-loaded with examples and usage commands, maximizing information density without redundancy.

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

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

Given the tool's complexity and lack of an output schema, the description fully covers what data is pulled, how results are sorted, and what the response includes (paired data + citation URIs). It also contextualizes when to prefer this over sequential lookups, making it complete.

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

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

Schema coverage is 100%, but the description adds significant context: type="company" pulls financial metrics, type="drug" pulls FAERS/FDA/trial counts, and values provides ticker vs drug-name examples. This raises the value above 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 tool performs side-by-side comparisons of 2–5 companies or drugs, with specific resource types (company vs drug). It distinguishes itself from sequential single-entity lookups, making its purpose unambiguous.

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

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

Explicit trigger phrases and usage context are given: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." This tells the agent when to use the tool and offers an alternative approach to avoid, making usage guidance strong.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account and paid-plan requirements, parallel decomposition across 5,462 tools, gaps[] never invented, contradictions[] for standard/thorough, semantic excerpting, citation fetchability guarantees, and expected latency. No contradiction with annotations.

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

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

The description is long but every sentence carries operational information—account requirements, alternatives, data source scope, return format, depth semantics, and runtime expectations. It is front-loaded with the most critical constraint (account/sign-in) and organized topically without fluff.

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

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

With no output schema, the description fully carries the return-format burden: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, gaps[], contradictions[], and excerpting behavior. It also covers prerequisites, use cases, and performance expectations, making the tool fully understandable.

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

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

Schema coverage is 100%, and the description enriches both parameters: it explains each depth level's behavioral consequences (gap recovery, lead-chasing, contradictions[] scan) beyond the enum labels, and clarifies the question parameter is meant for broad, multi-part natural-language queries where decomposition is the point.

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

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

The description clearly states a specific action—grounded multi-source research across Pipeworx's 1419 structured data sources—and distinguishes it from open-web search and from sibling ask_pipeworx. It names the exact scope and delivery format (findings packet with citations and gaps).

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 directs when to prefer ask_pipeworx (single lookup, current-news topics, unsigned-in users) and when deep_research is the right choice (broad/multi-part structured-data questions). It also provides depth-mode selection guidance and account/paywall prerequisites.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes further by explaining the result format: top-N tools with names, descriptions, and full input schemas with curated examples, and that results are ready to call directly with no second schema lookup. This is valuable behavioral disclosure beyond the annotations.

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

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

The description is front-loaded with the core purpose in the first sentence and uses the rest for context and output details. The domain list is somewhat long but directly helps the agent formulate queries, so it 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?

Despite having no output schema, the description specifies exactly what the tool returns (names, descriptions, full schemas, examples) and how to use it. It also addresses the main use case of tool discovery in a large toolset, making it complete for this meta-tool's job.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the query is a natural language description of data or task and lists example domains, but it does not add parameter-specific details beyond what the schema already documents.

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

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

The description opens with a specific verb and object: "Find tools by describing the data or task." It clearly distinguishes this from siblings by framing it as a meta-tool for discovering other tools, and the enumerated domains (SEC filings, FDA drugs, etc.) concretely scope the search space.

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 when to use this tool: "Use when you need to browse, search, look up, or discover what tools exist" and even instructs "Call this FIRST when you have many tools available." It lacks an explicit when-not-to-use clause, but the context is clear enough.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds significant behavioral context: parallel fan-out across sources, up to 5 filings with URIs, patents API sunset and soft-fail behavior, GDELT→GNews fallback, and return field structure. 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 a dense block but front-loaded with example queries and logically organized by input, behavior, and return fields. Every sentence contributes useful information, though it could be slightly tightened without losing substance.

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 thoroughly covers all return fields (cik, recent_filings with URIs, fundamentals, patents fallback, news chain, LEI), input constraints, and fallback behaviors. This is complete for an agent to decide when to invoke and what to expect.

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

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

Schema coverage is 100% and both parameters have detailed descriptions with examples and constraints (ticker or zero-padded CIK; only 'company' type). The description repeats these constraints but does not add new semantic meaning beyond what the schema already provides, 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 clearly states the tool's purpose with specific verbs ('full cross-source profile') and provides example user intents ('tell me about X'). It distinguishes from siblings by explicitly saying to prefer this over chaining single-pack lookups and directing name-only queries to resolve_entity.

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 ('when the user asks for a holistic view') and explicitly names an alternative (resolve_entity) for unsupported name inputs. Also notes 'ALWAYS PREFER' over chaining lookups, giving clear decision criteria.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that the output is raw text and covers a 3-day period, but provides no other behavioral details (e.g., update frequency, formatting).

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 concise sentence that conveys key information without redundancy.

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

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

Given the tool's simplicity, no parameters, and presence of an output schema, the description adequately covers the essentials. However, it lacks any usage context or alternative tool references, so it's not fully complete.

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

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

The tool has no parameters, so the schema is trivially covered. The baseline for 0 params is 4, and the description doesn't need to add 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 identifies the tool's output: a 3-day SWPC forecast discussion in raw text. This differentiates it from sibling tools like kp_index or aurora_forecast, which provide specific space weather metrics.

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

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

The description implies that this tool is used to retrieve the raw forecast discussion text, but it does not provide explicit guidance on when to use it over other space weather tools. No alternatives are named.

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 and idempotentHint, so the safety profile is covered. The description adds context that this applies to previously saved agent memories, but does not disclose additional behavioral details beyond what annotations provide.

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

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

Two sentences: first states the action, second provides usage guidance and tool relationships. Every sentence earns its place with no wasted words.

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

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

For a single-parameter delete operation with annotations covering destructiveness and idempotency, the description adequately covers purpose, usage, and relationships. No output schema is needed, and the tool's simplicity means no further detail is required.

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

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

Schema description coverage is 100% and the parameter 'key' is described as 'Memory key to delete'. The description's phrase 'by key' reinforces but does not add new semantic meaning beyond the schema.

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

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

The description uses a specific verb ('Delete') and identifies the resource ('a previously stored memory') and the method ('by key'). It clearly distinguishes this tool from siblings like 'remember' and 'recall' by specifying the deletion operation.

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 the tool: when context is stale, the task is done, or clearing sensitive data. It also references pairing with 'remember' and 'recall', giving relational guidance, though it does not provide explicit when-not-to-use scenarios.

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

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

The description discloses the operational flow (fetches the page, extracts title/description/key links, emits the markdown format) and the output form, which adds context beyond the annotations that already declare read-only and idempotent 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 four sentences, front-loaded with the primary action, and each sentence contributes distinct value: purpose, process, output, and use cases. The 'Useful for' list keeps it organized without wasted words.

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

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

The tool is simple (2 parameters, no output schema), and the description fully covers usage, output format ('a single text blob ready to drop at site-root/llms.txt'), and example scenarios. No significant gaps remain.

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

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

Both parameters are fully described in the schema (100% coverage), so the description does not need to compensate. It adds no additional parameter-specific meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb and resource ('Generate a production-ready llms.txt file for any URL'), and it distinguishes itself from siblings like ai_visibility_check by focusing on file generation rather than visibility analysis.

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

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

The description provides 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 say when not to use it or mention alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. But it adds only 'history,' which is a minimal behavioral trait. It does not disclose output characteristics, data source specifics, or any limitations, so it adds little beyond the annotations.

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

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

The description is a single three-word phrase with zero wasted words. It is front-loaded and immediately understandable, fitting the 'every sentence earns its place' criterion perfectly.

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 an output schema present and full parameter documentation, the description serves mainly to explain the tool's purpose. It does that minimally, but lacks usage context and sibling differentiation. For a simple read-only tool, it is adequate yet leaves room for improvement.

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%: the single 'window' parameter is fully described with its allowed values ('6-hour (default) | 1-day | 3-day | 7-day'). The description does not add any additional parameter meaning, but according to the rubric, baseline is 3 when schema coverage is high.

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 identifies the specific resource (GOES X-ray flux) and adds the scope 'history,' which clearly differentiates it from sibling space-weather tools like aurora_forecast or solar_wind. However, it lacks an explicit verb (e.g., 'retrieve' or 'get'), making it a noun phrase rather than a full command.

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 no guidance on when to use this tool versus alternatives. There is no mention of use cases, exclusions, or comparisons to siblings. The agent must infer from the name alone that this is for X-ray flux data.

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/idempotent, and the description adds detail on data freshness, observed vs forecast mix for the 7-day window, and the estimated nature of 'now' and '1-minute'. It also discloses the SWPC 30-day archive retirement, a meaningful behavioral limitation.

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 dense sentences with no filler; the core definition, window breakdown, and limitation are all front-loaded and prioritized.

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 data fetch tool, the description covers data source, all window semantics, and a key limitation. With an output schema present, this is ample 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 defines the one `window` param with allowed values, and the description adds semantics for each value: 'now' is a single freshest estimate, '1-day' is 3-hourly observed, '7-day' includes forecast with flags, '1-minute' is estimated for last ~6 hours. This fully enriches the parameter beyond the enum.

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 returns the NOAA planetary K-index, a 0–9 geomagnetic activity scale, and standard aurora/storm indicator. It distinguishes windows (now, 1-day, 7-day, 1-minute) and notes the Kp≥5 storm threshold, setting it apart from sibling tools like aurora_forecast or solar_wind.

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

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

Provides clear context for when to use: it is the standard Kp indicator with specific temporal windows and notes that no 30-day history is available, implicitly guiding against month-long requests. However, it does not explicitly name alternative tools or state 'use this when...' exclusions.

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

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

Annotations declare read-only, idempotent, and open-world hints. The description adds behavioral context beyond these annotations by specifying caller scope and the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is valuable for an agent deciding to invoke it.

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

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

Two sentences, each purposeful: the first states the function and return shape, the second states when to use it. No filler or redundant phrases, making it highly concise and well structured.

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

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

For a simple read-only list tool with one optional parameter and comprehensive annotations, the description adequately covers purpose, return values, and usage context. There is no output schema, but the description compensates by listing the return fields explicitly.

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

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

Schema describes include_inactive with 100% coverage including its default value, so the baseline of 3 applies. The description's 'active subscriptions' aligns with the default but adds no additional parameter meaning beyond what the schema already provides.

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

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

Description explicitly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the returned fields. This clearly differentiates it from sibling tools like subscribe/unsubscribe, which perform different actions.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indirectly references subscribe and unsubscribe, giving clear guidance on when to use the tool, though it does not name the 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?

Beyond annotations (which are all false and offer little guidance), the description discloses rate limits (5 per identifier per day), quota impact ('doesn't count against your tool-call quota'), and the operational consequence ('team reads digests daily and signal directly affects roadmap'). It also warns against pasting end-user prompts, showing an awareness of privacy/format 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 dense but well-organized: it opens with the core action, then explains each use case, followed by exclusions and message guidelines, and ends with operational notes. Every sentence contributes to the tool's effective use, though a minor trim could make it even more scannable. The use of dashes and parentheses aids 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?

The description fully covers the tool's purpose, usage conditions, exclusions, parameter expectations, rate limits, and impact. For a feedback tool with no output schema, it provides all necessary context for an agent to decide when and how to invoke it. Nothing critical appears missing.

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

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

The input schema already covers all parameters with full descriptions (100% coverage), so the baseline is 3. The description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and to avoid pasting prompts, which enriches the message parameter semantics. It also gives practical guidance for the context object (which tool/pack/vertical to reference), though this is largely redundant with the schema.

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

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

The description states a clear action ('Tell the Pipeworx team') and scope ('something is broken, missing, or needs to exist'), with specific feedback categories (bug, feature, data_gap, praise). It distinguishes itself from sibling tools by being the sole feedback channel, and the explicit 'ONLY for tools served by this Pipeworx connection' further clarifies its unique 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 when-to-use triggers (wrong/stale data, missing tool, praise) and an explicit when-not-to-use condition (feedback for other MCP servers). It also gives an alternative action ('file it with that server instead'), satisfying the 'when-not' and alternatives criteria fully.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: it is self-aggregating, derived from a specific analytics engine, contains no PII, and has a caching policy (5min–1h). This greatly exceeds what annotations alone provide.

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

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

The description is moderately long but well-structured: it starts with the core purpose, then enumerates return values, use cases, and data provenance/caching. Every sentence delivers useful information, though the use-case list adds length; it remains focused and easy to scan.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is fully complete. It covers the data source, output contents, use cases, privacy, and caching, leaving no significant gaps in understanding.

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

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

The schema already provides 100% coverage for the single 'window' parameter, including its enum values and the semantics of shorter vs. longer windows. The description repeats the window range but adds no new syntax or details beyond the schema, so it meets the baseline.

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

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

The description clearly states the tool's function: reporting what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on aggregated usage trends.

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 (e.g., discovering hot data sources, confirming canonical tools, checking alignment with typical agent needs). It does not explicitly mention exclusions or alternatives, but the use-case list gives clear guidance on when 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial behavioral context: how partition-check signals are computed, the semantic similarity threshold (Jaccard ≥ 0.30), placeholder filtering rules, the fill-check pricing against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. It also mentions skipped_low_similarity and null arb signals on placeholder-overload, which are not obvious from annotations. No contradiction with annotations.

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

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

The description is long but highly structured: it leads with the core purpose, then breaks down modes, semantic anchors, filters, response structures, fill-check logic, and sibling pointers. Each section is labeled and delivers dense, non-redundant information. There is no filler; every sentence contributes to correct invocation or interpretation of results.

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 and only two optional parameters, the tool's complexity is fully captured: input modes, algorithmic checks, edge-case filters, response fields, real-world trading advice, and cross-reference to a related tool. The description is self-contained enough for an agent to decide when to call it, what arguments to use, and how to interpret results, including failure modes (e.g., null arb signal, fill check warnings).

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

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

Schema coverage is 100%, but the description enriches both parameters significantly. For `event`, it explains what an event slug looks like with examples and notes that full URLs are accepted. For `topic`, it clarifies what a seed question looks like and how the tool searches and flattens related events. It also describes the output shape for each parameter mode (event vs topic), going well beyond schema field names.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then clearly distinguishes three invocation modes (no-arg trending scan, event mode, topic mode), each with concrete examples and distinct behavior, and even points to a sibling tool (polymarket_fill_risk) for custom sizing. This leaves no ambiguity about what the tool does and how it differs from related tools.

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

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

The description provides explicit when-to-use guidance: no args for trending, `event` recommended for a specific market, `topic` for cross-event scanning. It also gives negative guidance ('do not trade it' when realizable edge ≤ 0) and directs to alternates ('For custom sizing use polymarket_fill_risk'). This is exactly the kind of usage context an agent needs to choose correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level'), the rarity of concentrated longshots, the 24h-move warning, placeholder-slug filtering, sport-specific bias corrections, and the unreliability of Fed signals. This goes far beyond what annotations provide.

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

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

The description is long but every sentence earns its place. It is front-loaded with the main purpose, then structured into clear sections (model families, response structure, knobs, diagnostics). No fluff or redundancy; it packs a high density of useful information in an organized way.

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

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

With 9 parameters and no output schema, the description carries the full burden of explaining what the agent will receive. It thoroughly describes each response segment, the fields carried per opportunity, the diagnostic counters, and how to interpret empty segments. It even explains why Fed bets are excluded from ranking. This is rare completeness for a tool with no 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 already documents all 9 parameters. The description adds value by grouping knobs (e.g., TRADEABLE-EDGE KNOBS) and explaining the semantics of min_partition_leg_kelly vs min_kelly, and slippage_pp in the context of Polymarket's zero fees and typical spread. It doesn't add much for limit/window/category_filter, but the additional knob context justifies a score above baseline.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings by framing it as a discovery tool for 'what should I bet on today' and breaks down the three response segments, making it easy to understand what the tool does and how it differs from alternatives like polymarket_arbitrage.

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: agents discover opportunities without paging hundreds of markets. It explains the tradeable-edge knobs and diagnostics for tuning results. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool versus polymarket_arbitrage or polymarket_edge_tracker, so it stops short of full exclusion guidance.

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

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

The description discloses many behavioral details beyond annotations, including computation specifics (on |edge_pp_net|, signed by trade direction), snapshot creation triggers (cache-miss), data gaps, 60-day TTL, and the fact that decay is based on daily closes not intraday. This adds substantial context not visible in the annotations.

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

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

The description is long but well-structured, with sections for args, response, and limits. It is front-loaded with the core purpose. Every sentence carries relevant information, though it could be slightly tighter without losing value.

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

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

Given no output schema, the description thoroughly explains the response structure ('tracked[]', 'expired[]', 'snapshot_dates[]'), including field meanings and data caveats (snapshot gaps, TTL). This is complete coverage for a complex telemetry tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description repeats the defaults and adds a slight clarification (max 30 vs clamp 2-30), but it does not add significant meaning beyond the schema. It mentions 'lookback' and 'snapshot family' but these terms are already in 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 clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) by emphasizing persistence and time-series tracking.

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

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

The description provides clear context on when to use the tool: to assess edge persistence and decay, contrasting fresh vs. old wide edges. It implies this is for longitudinal analysis rather than a current snapshot, but it does not explicitly name an alternative tool for current edges. Thus, it gives clear context without explicit exclusions or sibling comparisons.

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

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

Despite annotations already declaring readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral detail: it walks the order-book ladder, returns specific fields (vwap_fill_price, slippage_pp, verdict), interprets size_usd differently for buys vs sells and for basket mode, and warns about partial-fill transformation into directional risk. This goes far beyond what annotations provide.

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

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

The description is long but densely informative, with a clear structure: purpose, requirements, SINGLE-MARKET mode, BASKET mode, and usage guidance. Every sentence adds value, and the critical 'USE THIS before...' warning is prominent at the end. It is well-organized and front-loaded.

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 return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, realizable_sum, capture_ratio, thin_legs, etc.). It covers prerequisites, parameter behavior, and risk implications, leaving no major gaps for a complex financial tool.

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

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

Schema coverage is 100%, but the description adds critical semantic context: which parameter is required for which mode, how side defaults are auto-derived from partition sum, and how size_usd is interpreted as 'max spend' vs 'target proceeds' and as 'settlement notional' in basket mode. This meaningfully enhances what the schema alone conveys.

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 distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, and it explains two distinct modes (single-market and basket) with concrete deliverables.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), which is more than the calibration examples.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type counters, and how spreads are calculated (Kalshi − Polymarket). No contradiction with annotations exists.

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

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

The description is long but front-loaded with the core purpose, followed by structured mode and safety-field details. Every sentence carries relevant information, but the density and length require careful reading, so it is not maximally concise. Appropriate for the tool's complexity.

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

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

Given the tool's moderate parameter count, no output schema, and complex cross-venue matching logic, the description is highly complete. It explains response contents, safety fields, temporal alignment, skipped-pair reasons, and practical limitations such as pre-mapped topics often being untradeable. This gives an agent sufficient context to set expectations and interpret results.

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

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

The input schema already covers all three parameters at 100% and documents the override behavior. The description adds value by explaining the two-mode abstraction and how the parameters interact (topic auto-fetch vs explicit kalshi_event_ticker/polymarket_event_slug overrides), which goes slightly beyond the schema but does not add every edge case.

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, actionable statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource, the action (computing/spreading), and the scope (two named venues), and it distinguishes itself from related tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides clear usage context by explaining two modes (topic shortcuts and explicit pairings), when the spread is meaningful ('when the bet shapes are equivalent'), and a strong caveat that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. However, it does not explicitly name alternative tools or state when to prefer this tool over sibling tools like polymarket_arbitrage.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds meaningful context: scoping by identifier (anonymous IP, BYO key hash, account ID) and the relationship with remember/forget. It does not contradict annotations, and the added scope details exceed baseline.

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 job: define, contextualize, and scope. No redundant phrases.

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

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

For a one-parameter, read-only memory retrieval tool with rich annotations and no output schema, the description covers purpose, usage, scope, and related tools. It is sufficiently complete.

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

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

The schema already documents the single 'key' parameter with 100% coverage, including the omit-to-list-all behavior. The description repeats this and adds examples of what keys might be (ticker, address, research notes), but does not add new syntax or format details. 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 opens with a specific verb ('Retrieve') and clearly identifies the resource ('a value previously saved via remember') and the alternative behavior ('list all saved keys' when key omitted). It distinguishes itself from sibling tools like remember and forget by naming them and their roles.

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

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

The description states when to use it ('to look up context the agent stored earlier') and provides a rationale ('without re-deriving it from scratch'). It does not explicitly name alternatives or exclusions, but the pairing with remember/forget clarifies the workflow. Lacks explicit when-not guidance, so 4.

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 and idempotent behavior. The description adds the key behavioral detail that setting mark_read:true mutates read state, so subsequent calls return only newer events. It also discloses the payload fields. There is no contradiction because the mutation is optional and clearly described.

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

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

The description is three sentences, each with distinct value: core function, return contents and filtering, and side-effect/alternative access. It is front-loaded and contains no 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?

The tool has no output schema, so the description covers the return payload shape and feed behavior, which is adequate. It also mentions the alternative endpoint for scripts, a practical detail. The remaining params (limit, unread_only) are left to the schema, which is acceptable given 100% schema coverage.

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

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

Schema coverage is 100%, but the description enriches parameters with an example ('sec_8k'), specifies since as an ISO timestamp, and explains the consequence of mark_read on future calls. This goes beyond the schema descriptions, which only state type/default values.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb + resource. It distinguishes this from the generic sibling 'alerts' by emphasizing the persisted feed, and it states exactly what the return contains (source, citation_uri, raw payload). This makes the tool's 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 says 'Polls work fine,' indicating the tool is designed for repeated polling. It also mentions the same feed is available at GET registry.pipeworx.io/alerts.json for scripts/dashboards, which is an alternative for non-agent contexts. While it does not explicitly compare to sibling tools, it provides clear usage context.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses significant behavior: parallel fan-out across sources, GDELT→GNews fallback under rate limiting/5xx, USPTO soft-fail until reactivation, and the return structure (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense but every sentence carries useful information. It is somewhat run-on, but front-loaded with user intents and then systematically covers sources, parameters, and output. No fluff; 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?

For a complex multi-source tool with no output schema, the description is exceptionally complete. It explains return format, fallback behavior, soft-failures, and parameter formats, and points to the alternative tool. This is enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds minimal extra semantic value — mostly redundant examples ('2026-04-01', '7d') and a recommendation ('30d' or '1m'), but does not fundamentally enrich the parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's purpose: a change feed for a company over a recent time window, with specific data sources (SEC, GDELT/GNews, USPTO). It uses a specific verb ('fans out') and resource ('change feed for a company'), and distinguishes from its sibling entity_profile.

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

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

The description opens with concrete query phrasings ('What's new with X', 'latest on Y') and explicitly directs users to entity_profile when a static profile is needed. It also clarifies the typical window usage ('Use 30d or 1m'). This gives clear when-to-use vs. 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?

Beyond annotations, the description discloses that data is stored as a key-value pair scoped by the agent's identifier, and that persistence varies (persistent for authenticated users, 24-hour retention for anonymous). It does not specify overwrite behavior on duplicate keys, but the idempotentHint annotation covers idempotency, so 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 four sentences, each adding distinct value: purpose, usage scenarios, storage mechanics + persistence, and companion tools. It is front-loaded and free of redundant phrasing.

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

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

For a simple two-parameter tool with no output schema, the description provides purpose, use cases, storage semantics, persistence behavior, and related tools. The only missing detail is duplicate-key overwrite behavior, but that is not critical given the idempotent hint.

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 descriptions already cover both key and value with examples and allowed formats. The description adds no new parameter-level semantics beyond mentioning 'key-value pair,' so it relies on the schema's 100% coverage.

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

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

The description uses the specific verb 'Save' plus the resource 'data the agent will need to reuse later,' clearly defining a memory-write operation. It distinguishes from sibling tools by explicitly mentioning pairing with recall (retrieve) and forget (delete), making its role unique.

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

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

Provides concrete when-to-use guidance with examples ('a resolved ticker, a target address, a user preference, a research subject') and states the persistence difference for authenticated vs anonymous sessions. It does not explicitly state when not to use, but the examples and complementary sibling references 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety profile. The description goes beyond these by disclosing that each call cascades through multiple internal lookup endpoints, that input is auto-disambiguated, and that it returns citation URIs. This adds meaningful behavioral context without contradicting the annotations.

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

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

The description is substantial but well-structured, starting with example queries, then usage guidance, then supported types. Every sentence contributes useful information, and the use of quotation marks and line breaks makes it scannable. It is slightly longer than necessary but not wasteful.

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

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

With no output schema, the description fully explains what the tool returns for each entity type, including specific fields (ticker, CIK, RxCUI, ingredient, brand) and citation URIs. It also explains the input flexibility and auto-disambiguation behavior. The combination of detailed parameter info and rich annotations makes this description complete for a resolver tool.

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

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

Schema coverage is 100% and the schema descriptions are already detailed, so baseline is 3. The description adds value by providing concrete examples of valid values (e.g., 'AAPL', '0000320193', 'ozempic') and explaining what each type returns, which enriches the meaning beyond the schema. It does not fully compensate for lack of output schema, but for parameter semantics it is strong.

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

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

The description uses specific verbs ('resolve', 'look up', 'find') and clearly states the tool's resource: converting user-spoken names into canonical identifiers. It gives concrete query examples and lists supported entity types, making it unmistakable what the tool does. It also differentiates itself by noting it should be used before other tools that require IDs as input.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', which is a clear usage directive. It also explains that it replaces 2-3 manual lookups, implying when it is appropriate. However, it does not explicitly mention when not to use it or name alternative tools, so it falls slightly short of the highest 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral details beyond the annotations: it explicitly states that each entity is probed with ai_visibility_check, results are ranked by score, and the output surfaces most/least recognized entities with score, confidence, and signal density. This goes beyond what annotations provide and accurately reflects the tool's operation.

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

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

The description is concise and well-structured: a clear opening statement of purpose, a mechanism sentence, a use-case sentence, and an output sentence. Each sentence earns its place with no redundancy. It is front-loaded with the core purpose and avoids any filler, making it easy to grasp quickly.

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

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

For a read-only tool with no output schema, the description adequately covers purpose, mechanism, use case, and output fields. It explains the ranking behavior and return values, and the schema fully documents parameters. It does not mention potential costs, rate limits, or error handling, but these are not critical given the read-only and idempotent nature declared in annotations. Overall, the description is sufficiently 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?

The schema provides complete descriptions for all 4 parameters (100% coverage), including details on models, _apiKey, context, and entities. The description adds no new parameter-specific semantics beyond reinforcing that the first entity is treated as the subject and the rest as competitors, which is already stated in the schema. Therefore, a baseline score of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes itself from sibling ai_visibility_check by emphasizing side-by-side comparison, ranking, and the competitive audit use case. The mechanism and output are also clearly described, leaving no ambiguity about what the tool does.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example query, implying this tool is for multi-entity comparisons. It references ai_visibility_check as the underlying probe, which indirectly suggests when to use each, but it does not explicitly state exclusions or alternative tools. Context is clear, but no explicit when-not guidance is provided.

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

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

Adds behavioral context beyond the readOnly/idempotent annotations, explicitly disclosing partial failure degradation, a 5-30s timing risk on first measurement, and the sources_failed field. 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?

Dense, well-structured description with no filler; every sentence contributes (purpose, return fields, ecosystem scope, failure behavior). Slightly long but each sentence justifies 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?

Despite no output schema, the description enumerates the summary fields, details, links, alternatives, and failure modes, making the tool's behavior and output fully predictable for a composite API call.

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% (package and version are fully documented). The description does not add parameter-level semantics beyond what the schema already provides, so it stays at the baseline of 3.

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

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

The description explicitly states the composite check purpose, names the data sources (deps.dev and bundlephobia), and scopes to npm packages. This clearly distinguishes it from sibling tools such as scan_competitor_ai_presence.

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

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

Provides explicit trigger phrases ('is X safe / popular / small') and names an alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: it returns top-N passages with offsets and similarity scores, truncates inputs beyond 200K chars with a flag, and describes the embedding/window approach. This goes well beyond structured annotations.

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

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

The description is front-loaded with the core action and uses compact, dense sentences. Each sentence earns its place: usage context, return format, pairing, and technical limits. No redundant or filler content.

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

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

Despite no output schema, the description explains the return format (passages with offsets and similarity scores), the use case (large records), limits (200K chars truncated and flagged), and even the mechanism (BGE embeddings, cosine, 500-char windows). It fully prepares the agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning about the text parameter by disclosing the 200K char cap and truncation behavior, enriching the parameter's semantics beyond the schema's basic description.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly defining the tool's verb, resource, and scope. It further distinguishes itself from siblings by explaining it operates on already-fetched text and explicitly pairs with ask_pipeworx_grounded, unlike broader query tools.

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

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

The description states 'Use when the record is too big to cram into the prompt,' providing explicit when-to-use guidance. It also explains how it complements ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages'), clarifying the workflow relative to an alternative.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying 1-minute cadence and the 24-hour data availability window, plus the important coordinate system distinction (GSE/GSM) for bz. 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?

Two sentences, dense with information: data source, measured quantities with units, magnetic field components, coordinate systems, cadence, and retention. No filler or redundancy; the description is front-loaded and every clause contributes 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?

The description covers the key aspects users need: data source, parameters, cadence, availability, and physical significance. With annotations covering safety and an output schema present, the description is sufficiently complete for a simple read-only data-fetch tool. The only minor gap is no explicit mention of the default window, but the schema already handles that.

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% coverage of the 'window' parameter with a detailed description of allowed values and the default. The tool description adds little beyond that, only reiterating the 1-minute cadence which is already implied by the schema. Per rubric, baseline 3 is appropriate when schema covers everything.

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

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

The description clearly identifies the resource ('solar wind from the active spacecraft (DSCOVR/ACE)') and enumerates specific data fields, distinguishing it from weather-alert or forecast tools. However, it lacks an explicit verb like 'get' or 'returns', instead opening with a noun phrase, which slightly reduces clarity.

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

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

The description provides clear context for when the tool is useful, especially the note that sustained southward bz_gsm drives geomagnetic storms, implying use for storm assessment. It does not explicitly mention alternative tools or list when-not-to-use scenarios, so it stops short of full explicit guidance.

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

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

The description adds significant behavioral context beyond annotations: OAuth requirement, phone verification for SMS, 10/day SMS cap, always-on feed, webhook signing secret returned once, and auto-disable after 10 consecutive failing runs. Annotations (idempotentHint, destructiveHint) are present but the description enriches them with actionable details.

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

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

The description is moderately lengthy but well-structured: main purpose, requirements, supported types, delivery channels. Each sentence adds value, though some redundancy with the schema exists (e.g., repeated type examples). It is organized clearly with logical flow, earning a 4.

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

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

Given the tool's complexity (nested objects, multiple types, delivery channels), the description covers prerequisites, supported types, delivery options, and return value. It also explains the always-on feed and webhook behavior, which is essential for usage. Without an output schema, the description compensates effectively.

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 detailed descriptions with 100% coverage, including type-specific params and delivery options. The description adds interpretive examples like items:["5.02"] = officer change and clarifies constraints like phone verification, which go slightly beyond the schema. Baseline is 3, and the extra context justifies 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 clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the resource (subscription to event stream), the action (create), and the return value (new subscription id). It also distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description implies usage context by explaining the need for a Pipeworx OAuth account and describing supported subscription types. It also mentions how to consume alerts via recent_alerts, hinting at an alternative. However, it does not explicitly state when not to use this tool or name alternatives like list_subscriptions for viewing existing subscriptions.

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, and non-destructive behavior. The description adds valuable context by detailing the return structure (category-bucketed examples, exact tool + argument shape), the live catalog source, and the effect of the optional topic parameter (full spread vs. focused). It goes beyond the annotations without contradicting them.

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

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

The description is dense but well-structured: it opens with natural user phrasings, states the core purpose, lists return contents, then gives explicit call instructions. Every clause contributes value, but the single long paragraph with em-dash lists is somewhat heavy and could be broken into shorter sentences for faster scanning.

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 1-optional-parameter tool with strong annotations and no output schema, the description covers all essentials: onboarding use case, return format, the topic parameter's behavior, and relationship to meta-tools. It is fully self-contained for an agent deciding whether and how to invoke it.

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

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

The schema already covers the single topic parameter at 100% with a description. The tool description adds meaningful guidance beyond the schema by giving concrete example topic values and explaining the behavioral difference between omitting topic (full cross-category spread) and passing it (focused results), which is not in the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for Pipeworx, stating it returns category-bucketed example questions with exact tool/argument shapes. It uses a specific verb ('returns', 'learn how to call') and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by positioning itself as the 'FIRST' step for unknown capabilities.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or pass the topic parameter. It also names the meta-tools (ask_pipeworx, entity_profile, compare_entities) as things to learn, providing context versus alternatives, though it doesn't explicitly say 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?

Beyond annotations, it discloses the non-destructive nature ('deactivated, not deleted') and the availability of historical events via recent_alerts. This adds meaningful behavioral context and is consistent with annotations.

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

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

Three sentences, front-loaded with the core action, and every sentence adds essential information without fluff. Efficient and well-organized.

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 tool with annotations covering safety, the description covers ownership constraints, the deactivation behavior, and the historical-event implication. No gaps remain.

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

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

The schema already provides 100% coverage for the id parameter, including its uuid type and origin ('returned by subscribe'). The description adds only 'by id' which is redundant, so no significant extra 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 action ('Cancel'), the resource ('subscription'), and the method ('by id'). The ownership enforcement detail also distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

It provides clear context: ownership is enforced (only your own subscriptions), and the effect is deactivation rather than deletion. This implies when to use it and what to expect, though it doesn't explicitly name alternatives or exclusions.

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

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

Annotations already mark it readOnly/openWorld/idempotent, so the bar is lower. The description adds valuable context: it discloses the structured vs. grounded pipeline, the verdict types, the citation mechanism (pipeworx://), and the fact that it replaces multiple sequential calls. This goes beyond annotations without contradicting them.

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

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

The description is detailed but well-organized, front-loaded with trigger phrases and a clear purpose. Each sentence adds value, including the note about replacing 4-6 calls. It is slightly long but appropriate for a tool with this 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 no output schema, the description adequately covers return values (verdict types, actual value, citation, reasoning) and use cases. It explains the two processing paths and the fallback behavior. Minor gaps exist (e.g., error handling), but overall the description is sufficient for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description gives an example for the 'claim' parameter but doesn't add significant parameter-specific semantics beyond what the schema already provides. The tolerance_pct parameter is well-documented in the schema; the description doesn't elaborate on it further.

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

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

The description clearly identifies the tool as a claim verification tool with specific verb+resource ('fact check', 'verify the claim'). It distinguishes from siblings by explicitly scoping to natural-language factual claim verification and detailing the two processing paths (financial vs. other). Example trigger phrases aid recognition.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the fallback behavior for non-financial claims. However, it doesn't name alternative tools or state when not to use this tool, so it lacks explicit exclusions.

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