Nasa

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the return format (per-model object with score, confidence, signals, raw_response + combined view) and the cost implication of using Anthropic (BYO key, pay Anthropic). This complements the annotations well.

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 dense sentences, no wasted words. The core action and output are front-loaded (first sentence). Additional details about models, API key, and return format are efficiently packed. Every sentence earns its place.

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

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

For a tool with 4 params, no output schema, and annotations covering safety, the description is complete enough. It covers use case, parameter selection, and return structure. One could imagine mentioning pagination or rate limits, but the tool appears to return a combined view without pagination, so it's 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?

Schema coverage is 100%, so the schema already documents parameters. The description adds meaningful context: default model identity (Workers AI Llama-3.3-70b), that it's free, that `_apiKey` is only needed for Anthropic, and that `context` disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probe, distinguishing it from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence' which focus on entity resolution or competitive scanning rather than AI model awareness.

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

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

The description explicitly mentions utility for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It explains when to use the free Workers AI model and when to provide an API key for Anthropic. While it does not explicitly list alternatives or exclusions, the context is clear and practical.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: routing, automatic argument filling, structured answers, stable citation URIs, and 'one fast call'. This exceeds the baseline without needing to repeat annotation 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 relatively long but front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and organized into clear sections: scope, mechanism, examples, and alternatives. Each sentence adds value, though a few examples could be trimmed without losing essential guidance.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns, what it routes through, when to use it, and when to use alternatives. It covers examples, scope of sources, and the key differentiators. This is complete enough for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the schema already documents the `question` parameter and its aliases. The description reinforces that the input is a natural-language question and provides examples, but it does not add substantial parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a router for factual questions, stating it routes to 5,798 tools across 1,517 sources and returns structured answers with citation URIs. It uses specific verbs and resources, and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them directly.

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

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

The description gives explicit when-to-use guidance: prefer over web search, use for factual queries, and start here for most questions. It also provides clear alternatives with conditions: ask_pipeworx_grounded for grounded answers with verbatim evidence, and deep_research for broad or multi-part questions.

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

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

Beyond the annotations (read-only, open world, idempotent, non-destructive), the description discloses that this is an experimental edge, that candidate routing improvements may be active, and that currently no candidate is active so behavior matches the stable router. It also clarifies there is no fallback and that this is a fully working router. It does not address rate limits or error behavior, but the annotations already cover the safety profile.

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

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

Four sentences, front-loaded with the tool's identity and the key usage condition. The status detail and no-fallback clarification are useful, though the sentence about outcome evidence and the retirement date is somewhat internal-metadata rather than essential agent guidance. Overall it is compact and scannable.

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 alias-only input schema, no output schema, and rich annotations, the description fully covers what an agent needs to decide and invoke the tool. It explains the experimental nature, current exact-equivalence with ask_pipeworx, the routing guarantee, and the intended use case. Nothing critical is missing.

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

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

The schema already documents all six parameters and aliases with 100% coverage, so the description does not need to repeat them. The description only says 'same arguments' as ask_pipeworx, which adds no parameter-level detail. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta universal router with the same 5,798 tools, arguments, and response shape as ask_pipeworx. It distinguishes the tool from the stable ask_pipeworx sibling by emphasizing the experimental routing edge. It leans on the title rather than a strong verb like 'routes', but the tool's role is unambiguous.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and states that results are compared against the stable router. This gives an agent a concrete condition for choosing this tool over the sibling. It also explains the current state where no candidate is active, so the tool currently matches ask_pipeworx exactly.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing that answers are extracted strictly from tool output, that refusals occur with specific reasons, and that success includes verbatim evidence. It also flags the extra LLM call cost, which is important behavioral context annotations cannot convey.

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

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

Every sentence earns its place: purpose, routing behavior, return/refusal shape, when-to-use, and cost tradeoff. The most important differentiator is front-loaded, and the length is justified by the richness of behavioral and usage information packed into a compact space.

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 present, the description properly covers both success and refusal return shapes, including refusal_reason enumerations. It also covers cost, alternatives, and use cases, leaving no critical gap for an agent deciding whether and 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 description coverage is 100%, and the schema fully documents the single question parameter and its aliases. The tool description adds no parameter-specific detail, but none is needed because the schema already carries the full semantic load; 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 opens with a clear specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It states the workflow — routing, fetching, and extracting an answer only from tool results — and differentiates itself from the sibling ask_pipeworx by emphasizing groundedness, evidence, and explicit refusals.

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?

Usage guidance is explicit: use it when 'an answer will be quoted, cited, or acted on' and the agent 'must not invent facts.' It also names the preferred alternative for casual lookups: 'prefer ask_pipeworx for casual lookups,' with a concrete cost tradeoff ('Costs one extra LLM call').

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

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

The description extensively covers behavioral traits beyond annotations: resolution confidence, market matching, closed market handling, wide spread warnings, resolution-rule risk, and safety short-circuits. All align with readOnlyHint and non-destructive hints.

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

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

Very long, dense paragraph without section breaks. While packed with value, it could be more scannable with headers or shorter sentences. Some redundancy exists (e.g., resolution risk details).

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

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

Given the complexity (3 parameters, no output schema), the description covers input formats, classifiers, fan-out, response shapes, resolver contract, parent events, news fallbacks, safety, closed markets, spreads, and cancellation rules. Very thorough.

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 description adds significant meaning: market can be slug, URL, or text; depth enum explained; include_raw with payload size guidance. This goes beyond the schema alone.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data. It specifies the verb 'Research' and the resource 'Polymarket bet', and distinguishes from sibling tools like polymarket_arbitrage by focusing on data gathering and edge 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?

Explicit usage cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides examples of fan-out for different bet types, but lacks explicit when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: for company type, it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for drug type, it pulls FAERS, FDA, trial counts; results sorted by primary metric; returns paired data with citation URIs. 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 paragraph that efficiently front-loads usage patterns and key details. Every sentence adds value, with no redundancy or fluff. It is concise yet comprehensive.

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 simple schema (2 parameters, no output schema), the description fully explains the return format (paired data, citation URIs, sorted), data sources, and behavior per entity type. It compensates for the lack of output schema and provides all necessary context for correct invocation.

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

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

Schema has 100% coverage with descriptions for both parameters (type enum and values array). The description adds further semantics: explains that for company, values are tickers/CIKs; for drug, values are names; and provides examples. This goes 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 purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists trigger phrases like 'Compare X and Y', 'which is bigger', etc., and distinguishes from sequential lookups, which is also a sibling tool (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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' and notes it replaces 8–15 sequential lookups. This provides clear when-to-use guidance and implies when not to use (single entity lookups).

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, but the description goes far beyond them. It discloses parallel routing across 5,798 tools, the findings packet structure (evidence, confidence, source, fetched_at, citation_uri), gap recovery behavior, contradictions[] for standard/thorough, semantic excerpting, latency expectations, and account/paid requirements. There is 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 dense, front-loading the critical sign-up requirement and the alternative tool before the core purpose. Every major clause adds unique context: latency, citation resolvability, excerpting behavior, depth semantics. Some inline stylistic noise ('IN PARALLEL') and heavy use of parentheses make it slightly harder to scan, but the length is justified for a tool with this complexity and no output schema.

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?

Because there is no output schema, the description carries the full burden of explaining return values. It does so thoroughly: findings packet with fields, gaps[], contradictions[], citation_uri resolvability, and depth-dependent behavior. It also covers auth, signup link, latency, and when to use an alternative. The agent has all essential information to decide whether and how to invoke this 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%, so the baseline is 3. The description adds value beyond the schema by explaining the behavioral implications of each depth tier (hop strategies, gap recovery, contradiction scans, paid requirement) and by noting that the question parameter is meant for natural-language, broad/multi-part questions. This is meaningful extra context beyond enum labels.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. It explicitly contrasts with open-web search and with sibling ask_pipeworx, and clarifies it is for broad/multi-part questions over structured data as opposed to single lookups. This lets an agent distinguish it from the many sibling 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 names exact alternatives and conditions: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and notes a paid plan is required for depth:'thorough'. It also identifies the best use case for deep_research, so the agent knows when to select it versus alternatives.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating safe, non-destructive reads. The description adds behavioral value beyond annotations: it explains that each result includes full input schemas with curated examples, ready to call directly without a second lookup. 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?

Description is moderately long but well-structured: core purpose first, then usage context, then return details, then call guidance. Every sentence adds value. Could be slightly tightened but remains efficient.

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

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

Given the tool's complexity (discovery among many siblings) and absence of output schema, the description sufficiently explains what is returned (top-N tools with names, descriptions, and full input schemas with examples). It covers the key aspects an agent needs to understand the tool's role.

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% (6 parameters all described). The description adds meaning by clarifying that query accepts natural language and multiple aliases (q, task, description, search) are interchangeable. It also mentions default and max limit values (20, 50), which are present in the schema but reinforced.

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

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

The description starts with 'Find tools by describing the data or task,' providing a specific verb and resource. It clearly distinguishes this discovery tool from the many sibling tools (e.g., get_asteroids, get_mars_photos) by stating it returns the top-N most relevant 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?

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context on when to use it. While it doesn't explicitly list when not to use, the recommendation to use it first implies its role as a navigational tool.

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

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

The description discloses rich behavioral detail beyond the readOnly/idempotent annotations: USPTO PatentsView sunset soft-fails, an FDA section with no biologics is normal, sources_used/sources_failed indicate real no-data, private companies return resolved:false with notes, and names resolve via SEC EDGAR. This goes far beyond what annotations provide and prevents misinterpretation.

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 dense and front-loaded with purpose and usage before source and return details. Every sentence carries necessary behavioral or routing information; a slight restructure into shorter bullets could improve readability, but nothing here is filler.

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

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

Given there is no output schema, the description fully compensates by enumerating the returned sections, interpreting empty sections, explaining fallback chains, and specifying input and resolution behavior. It even covers failure modes and API sunset conditions, making the tool safely invocable by an agent with no additional context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantic extras: type accepts 'company' or 'ticker' interchangeably, value can be a ticker, zero-padded CIK, or company name, and name resolution behavior is clarified. It reinforces and expands on the schema without introducing new ambiguity.

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

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

The description names a specific, differentiated action: producing a full cross-source profile of a US public company in one parallel call, with concrete user-phrase examples. It also distinguishes itself from chaining individual SEC/XBRL/news lookups, so an agent can tell it apart from narrower or broader 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a clear when-to-use rule. It also gives exclusions: private companies yield resolved:false with notes, and person/place is 'coming soon,' signaling this tool is scoped to companies.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not detail other behaviors like permissions or error handling. Adds some value 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?

Two concise sentences: first states action, second provides usage guidance. No fluff, front-loaded with purpose.

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

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

Given simplicity (1 param, no output schema) and good annotations, description covers purpose, usage, and pairing. Missing detail on reversibility or non-existent key behavior, but acceptable for a simple destructive 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 the single parameter 'key' with clear description. Description does not add extra semantic meaning beyond what the 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?

Description uses specific verb 'Delete' and resource 'previously stored memory by key', making purpose clear. It mentions pairing with remember and recall but does not explicitly differentiate when to use each sibling.

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 contexts: 'when context is stale, the task is done, or you want to clear sensitive data'. No explicit when-not-to-use or alternatives, but the pairing hint partially covers guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: it fetches a page, performs extraction, and emits markdown. There is no contradiction with annotations and the added detail clarifies expected side effects (none beyond a network fetch).

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: three sentences covering action, process, and use cases with no redundant content. Information is front-loaded and efficient.

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

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

Given the low complexity (2 params, no output schema) and comprehensive annotations, the description fully covers the tool's purpose, behavior, and output format (single text blob). No gaps remain for an AI agent to select or 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% for both parameters (url and max_links), so the baseline is 3. The description does not add new parameter-level meaning beyond restating the schema's descriptions, though it frames the use context. No additional enumerations or constraints are provided.

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

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

The description clearly states the verb 'Generate' and resource 'llms.txt file', specifies the purpose ('so AI crawlers can index the site cleanly'), and details the process (fetches page, extracts title/description/key links). It is well distinguished from sibling tools, none of which generate llms.txt.

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 lists three explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) which guide when to use. It does not explicitly state when not to use or name alternative tools, but the guidance is clear enough for an AI agent.

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 addition of 'with explanation' and the example add context but do not significantly enhance behavioral understanding beyond annotations. 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?

Two sentences plus an example, with no wasted words. The most critical information (what it does and the optional date) is 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?

Given the existence of an output schema (handling return values), the description completely covers what an agent needs to know: it retrieves APOD with explanation, optionally for a date. Examples further aid 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?

Schema coverage is 100%, so baseline is 3. The description reinforces optionality and provides an example, but does not add new meaning beyond the schema's 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 retrieves the NASA Astronomy Picture of the Day with an explanation, and the name and title reinforce this. It is distinct from sibling tools like get_asteroids or get_mars_photos, which focus on different NASA data.

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

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

The description explains when to use the tool (to get APOD) and mentions the optional date parameter. However, it does not explicitly state when not to use it or provide alternatives, though siblings are sufficiently different that guidance is less critical.

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 that it returns size, velocity, and miss distance, which is consistent and provides extra behavioral context without contradicting annotations.

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

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

The description is two sentences plus an example, with no unnecessary words. It is front-loaded with the purpose and constraints, making it highly efficient.

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

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

Given the annotations covering safety and idempotency, the output schema, and the description mentioning return fields, the tool definition is fully complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the description adds value by providing an example call and clarifying the date range constraint. This goes beyond the schema's property descriptions, earning a 4.

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

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

The description clearly specifies the verb 'get', the resource 'near-Earth asteroids', and the constraints 'within a date range (max 7 days)'. It also lists key return fields, making it distinct from siblings like get_apod or get_mars_photos.

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 the maximum date range of 7 days and provides an example, giving clear usage context. However, it does not explicitly mention when not to use this tool or suggest alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds keyless access, image resolution details, and capture time fields, enriching the behavioral context without contradiction.

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

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

Front-loaded with query examples, but slightly verbose. Every sentence adds value, though a minor trim could improve 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?

For a query tool with an output schema, the description fully covers input, constraints, and examples. No missing context for an agent to invoke correctly.

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

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

Schema coverage is 100%, and description adds context like default limit, short forms for cameras, and explanation of sol meaning. Examples further clarify usage.

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

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

The description clearly states the tool retrieves raw images from NASA's Perseverance rover with filtering by sol and camera. It distinguishes itself from siblings like search_nasa_images by specifying it covers only Perseverance.

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 query examples and guidance on when to omit parameters. Explicitly excludes other rovers (Curiosity, Opportunity, Spirit), telling the agent when not to use this tool.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, read-only behavior. Description adds no behavioral details beyond the annotations, but does not contradict them.

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

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

Two sentences, no fluff. First sentence states purpose and return data, second provides usage examples. Efficient 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?

Covers what is returned and typical use cases. Lacks mention of default date ranges (handled by schema). Overall complete for a simple read-only tool.

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

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

Schema coverage is 100%, and description does not add parameter details beyond the schema. Baseline score of 3 applies per rules.

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 clearly states the tool gets recent solar flares from NASA DONKI data, lists returned fields (class, times, source region, active region number), and provides example queries. Differentiates from siblings like get_apod and get_asteroids by focusing on space-weather data.

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

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

Explicitly describes when to use (e.g., 'recent solar flares', 'is there solar activity / a solar storm'). Does not mention when not to use or alternative tools, but context makes it clear this is for space-weather queries.

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, effectively communicating safety. The description adds details about returned fields but does not disclose additional behavioral traits such as pagination or rate limits. With strong annotations, a baseline score is appropriate.

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 with no wasted words. Front-loaded with purpose, then return fields, then usage guidance. Efficiently 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?

Given the tool's simplicity (one optional parameter, no output schema needed), rich annotations, and full schema coverage, the description is complete. It sufficiently explains what the tool does and when to use it.

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

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

Schema coverage is 100% with a clear description for the only parameter, include_inactive. The description does not add further semantics beyond the schema, so a baseline score of 3 is suitable.

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

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

The description clearly states 'list the caller's active subscriptions'—a specific verb (list) and resource (subscriptions) with scope ('caller's active'). It also enumerates return fields, distinguishing it from siblings like subscribe and unsubscribe.

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

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

Provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention when not to use or alternatives, but the context among sibling tools like subscribe/unsubscribe makes this acceptable.

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 all-false annotations, the description discloses the claim_token return behavior ('Filing without an account returns a `claim_token`'), rate limiting ('Rate-limited to 5 per identifier per day'), and cost semantics ('Free; doesn't count against your tool-call quota'). These are behavioral traits not visible in annotations or schema.

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?

Front-loaded with the purpose, then compactly covers exclusions, claim-token workflow, and rate limits. Every sentence carries distinct operational information with no filler, despite being a single dense paragraph.

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

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

With no output schema, the description still explains the key return behavior (claim_token), limitations, and scope. Combined with the rich optional schema, an agent has enough context to decide when and how to invoke this 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%, giving a baseline of 3. The description adds practical context for the message field ('don't paste the end-user's prompt') and the claim_token workflow (pass it back as pipeworx_feedback({claim_token:"pwfb_…"}) to check status), which the schema only partially 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 first sentence, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' states a specific verb and resource, clearly distinguishing it from sibling research/query tools. It also enumerates feedback categories (bug, feature/data_gap, praise) and scopes it to Pipeworx connection 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?

It explicitly says 'Use when a tool returns wrong/stale data (bug)...' and provides a hard exclusion: 'ONLY for tools served by this Pipeworx connection' — with the alternative of filing with the other MCP server. This is clear when-to-use vs. 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: self-aggregating signal, derived from CF analytics-engine, no PII, and caching details (5min-1h). No contradiction.

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

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

Three sentences, no fluff. Front-loaded with main output and immediate use cases. Every sentence earns its place with actionable information.

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

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

Given no output schema, the description adequately explains return structure (top tools, packs, call volume) and caching. It could mention count or format details for completeness, but overall sufficient for a simple read 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 the single parameter (window) with enum and 100% description coverage. Description adds behavioral nuance: shorter windows show hot now, longer windows show steady-state demand, which aids selection.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. Specific verbs like 'returns' and use cases (discovering hot data, confirming canonical choice) make the purpose distinct from sibling 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?

Explicitly lists three use cases and explains how window choice affects results. However, it does not mention when not to use this tool or name specific alternatives, leaving room for improvement.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) match the scanning nature. The description adds rich behavioral context: monotonicity checks, partition logic, semantic anchor, fill check mechanics, and response structure. 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 thorough but slightly verbose. It uses section-like structure (monotonicity, semantic anchor, partition filter, fill check) and front-loads the core purpose. Every sentence adds value, though some details could be streamlined.

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 comprehensively details the response structure (opportunities[], partition_check, fill check results) and covers edge cases (skipped_low_similarity, placeholders filtered, thin_legs). References related tool for custom sizing.

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 meaning beyond field names: explains each mode's behavior, gives example values ('fed-decision-may-2026'), and describes default behavior when no arguments are passed.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (default, event, topic) and distinguishes from sibling tools, none of which perform 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?

Explicitly tells when to use each argument: no args for trending scan, 'event' for a specific market slug, 'topic' for cross-event scanning. Includes guidance on when not to trade (fill check yielding realizable_edge_pp <= 0).

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 indicate read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond by detailing caching, edge calculation, slippage, model families, diagnostics, and knob effects, leaving no behavioral ambiguity.

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 structured with numbered segments and bolded terms, but it is verbose. While the detail is useful, it could be trimmed to improve conciseness without losing crucial information.

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

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

Given the complex behavior, 9 parameters, and no output schema, the description covers output structure, caching, knob effects, and diagnostic information, making it complete for an agent to use 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?

Schema coverage is 100%, but the description adds significant nuance to each parameter—e.g., explaining slippage context, min_kelly filtering rationale, and tradeable-edge knobs. This extra context is valuable for proper tool invocation.

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

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

The description clearly states that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using a specific verb-resource pair. It distinguishes itself from siblings by detailing its unique model families and 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 positions the tool for 'what should I bet on today' and explains the segments and knobs, providing clear usage context. However, it lacks explicit guidance on when not to use it or direct comparison to sibling tools, which would improve clarity.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it uses daily snapshots, tracks time-series, notes gaps from cache-misses, and discloses limitations like 60-day TTL and daily close decay. 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?

Description is well-structured: purpose first, then parameters, response details, limitations. It is thorough but slightly verbose; every sentence adds value but could be tightened.

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

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

No output schema exists, so description fully explains return structure: tracked[], expired[], snapshot_dates[] with field meanings and examples. Covers limitations and edge cases (gaps, TTL). Complete for a time-series analysis tool.

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

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

Schema coverage is 100%, baseline 3. Description adds default values and clamp for days, and default window, but these are already in schema. No additional meaning beyond schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and narrowing, distinguishing it from the sibling tool polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description explains when to use it: to assess whether an edge is fresh or old, with the example that a 3-week-old wide edge is different. It implies the alternative is polymarket_edges for current edges, but does not explicitly list 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 the annotations (readOnlyHint, idempotentHint, etc.), the description reveals internal behavior: it walks the order-book ladder, computes VWAP fill price, slippage, and returns a verdict. It warns about thin books and forced directional risk. This adds significant behavioral context that annotations alone do not 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 well-structured with clear section headers (SINGLE-MARKET, BASKET) and uses capitals for key requirements. It is somewhat verbose but every sentence adds necessary detail for a complex tool. It could be slightly more terse but remains effective.

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

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

Given the tool has no output schema, the description thoroughly explains return fields (top_of_book, vwap_fill_price, etc.) and covers edge cases like thin_legs and forced_directional_risk. It also mentions usage context (above ~$500, arb signals). The description is complete for an agent to understand inputs, outputs, and risks.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by explaining the dual-mode interpretation of side (auto for baskets) and clarifying that size_usd is settlement notional for baskets. This extra context justifies a score of 4.

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

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

The description opens with a precise verb+resource: 'Realizable-vs-theoretical edge check' against 'live CLOB order-book depth'. It distinguishes itself from siblings by explicitly stating to use this before acting on polymarket_arbitrage or polymarket_edges signals, and it outlines two distinct modes (single-market and basket) with clear definitions.

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 (partial basket fills convert arb into unhedged directional position) and states the required parameters (market or event), effectively telling the agent when to choose this tool over siblings.

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

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

Despite annotations already marking the tool read-only and idempotent, the description adds substantial behavioral context: compatibility codes, token-overlap matching rather than a shared resolution source, gross-vs-net fee disclosure, skipped leg counters, and the precise meaning of null temporal_alignment. This far exceeds what the annotations convey.

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

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

The description is long but deliberately structured with clear mode, response, safety-field, and fee disclosures. Most sentences carry unique information — compatibility codes, skipped-classification behavior, and null semantics. It is somewhat dense and could be pruned around repeated warnings, but it remains front-loaded and information-dense.

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

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

For a tool with no output schema and three optional parameters, the description is exceptionally complete. It covers return shape, safety flags, edge cases, fee modeling limitations, skipped-leg semantics, and real-world caveats about pre-mapped topics. An agent has enough context to call the tool correctly and interpret results without further discovery.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that explicit parameters override the topic-mapped side, that both modes run the identical matcher, and that topic values are pre-mapped shortcuts. This makes the parameter behavior clearer than the schema alone.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It precisely defines the tool's scope and differentiates it from the broader arbitrage-focused siblings by emphasizing cross-venue spread matching rather than single-venue edges or execution.

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

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

The description clearly explains when to use each of the two modes: 'topic' for pre-mapped macro shortcuts and explicit ticker/slug for custom pairings. It also gives practical guidance like 'pre-mapped ≠ tradeable' and notes that most topics return compatibility warnings. It does not explicitly name sibling alternatives or state when to prefer them, but the operational guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond this by stating the scope ('Scoped to your identifier...') and the dual behavior of retrieval vs. listing. No contradiction with annotations.

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

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

Two sentences front-load the core action, include context, and mention related tools. No fluff; every sentence is informative and necessary.

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 simple tool (1 optional parameter, no output schema), the description covers behavior, scoping, and relationship to siblings completely. No gaps remain for effective agent use.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description largely restates schema info but adds the context of listing when key is omitted. Since schema does heavy lifting, extra value is minimal but present.

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

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

The description clearly states the tool 'Retrieve[s] a value previously saved via remember, or list all saved keys' with a specific verb and resource. It distinguishes itself from siblings like remember and forget by explicitly naming them, providing clear scope.

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 explains when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember/forget. It does not explicitly exclude alternatives, but the context is clear enough for an AI agent.

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 behavioral details beyond the annotations: it specifies returned fields (source, citation_uri, raw payload), explains the 'mark_read' behavior, and mentions the feed is persisted. Annotations already indicate readOnly and idempotent, so the description complements without contradiction.

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

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

The description is concise: two sentences, front-loaded with purpose, and each word adds value. No redundancy, efficient structure.

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 covers return fields and key behaviors (mark_read, polling). It could mention ordering (most recent) but lacks details on pagination behavior for 'limit'. Still, it is largely complete for a read-only tool.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value by providing usage examples (e.g., filter by type 'sec_8k', use ISO timestamp for 'since', and set 'mark_read:true') that clarify how parameters are used together.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. It uses specific verbs like 'pull' and 'returns', and identifies the resource ('subscription feed'). However, it does not explicitly distinguish itself from sibling tools, leaving some ambiguity.

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 usage context: 'Polls work fine' and mentions an alternative endpoint for scripts/dashboards. It implies this tool is appropriate for polling, but does not explicitly state when not to use it or compare with other tools like 'subscribe' or 'list_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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds rich behavioral detail: fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and grouping of results. No contradictions with annotations. This 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 front-loaded with example queries, making the tool's intent instantly clear. Despite its length, every sentence adds necessary detail about sources, fallbacks, parameter formats, and return structure. No redundant or vague statements.

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 3 parameters, 100% schema coverage, no output schema, and no nested objects, the description is remarkably complete. It explains the tool's multi-source behavior, parameter options, output structure (changes[], total_changes, citation URIs), and provides sibling differentiation. No additional details are needed for an AI agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is high. The description adds value by explaining accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and providing a concrete monitoring recommendation. It reinforces the 'value' parameter can be ticker or CIK, and the 'type' enum is limited to 'company'. This aids parameter utilization 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 provides a 'change feed for a company in the last N days/weeks/months' and lists specific data sources (SEC EDGAR, GDELT→GNews, USPTO). Example queries like 'what's new with X' and 'latest on Y' make the purpose immediately recognizable. It explicitly distinguishes from sibling tool 'entity_profile', which provides static profiles.

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

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

The description provides strong guidance on when to use this tool versus entity_profile: 'Use entity_profile instead when you want the static profile.' It also gives example queries and parameter hints (e.g., '30d' for typical monitoring). However, it doesn't explicitly state when not to use it beyond the sibling comparison.

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 indicate idempotence and non-destructiveness. Description adds key behavioral details: scoped by identifier, authentication-based persistence (persistent vs 24-hour TTL), and storage as key-value pair. 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?

Four tight sentences front-loading purpose, followed by usage context, behavioral details, and tool pairing. 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 simple 2-param tool with no output schema, the description fully covers purpose, usage patterns, persistence details, and relationships to sibling tools. Complete and self-contained.

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 both parameters with descriptions. Description adds real-world examples (ticker, address, preference) and clarifies value is free text, enhancing the schema's explanation.

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 clearly states 'Save data the agent will need to reuse later', specifying a verb (save) and resource (key-value pair). It distinguishes from sibling tools like recall and forget, which are retrieval and deletion respectively.

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: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, but does not explicitly exclude scenarios like transient data requiring no persistence.

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, so the description is not repeating those. It adds valuable behavioral context: the tool cascades through multiple lookup endpoints, explicitly lists unresolved identifiers under `unresolved` rather than omitting them, handles ambiguous matches with `figi_candidates`, and degrades gracefully if GLEIF/OpenFIGI are unavailable while still returning EDGAR data. 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 not wasteful—every clause carries operational weight (source coverage, ambiguity handling, fallback behavior). It is front-loaded with the purpose and the key 'Use FIRST' directive, then expands systematically. A 4 reflects that it is appropriately sized for a complex tool, though a tighter version could trim some redundancy without losing essential detail.

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

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

For a complex tool with no output schema, the description fully equips the agent: it explains input semantics, expected outputs (identifiers, unresolved field, figi_candidates), multi-source behavior, ambiguity handling, and graceful degradation. It also notes that using it replaces 2-3 manual lookups, setting expectations on cost/performance. Nothing an agent needs to call it correctly is missing.

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

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

While the schema describes both parameters, the description adds crucial meaning beyond the schema. For `type`, it details what each enum value resolves (company: CIK/ticker/LEI/FIGI with ownership; drug: RxCUI/ingredient/brand). For `value`, it clarifies that the input must be the exact issuer name for bonds, not the full noun phrase, and warns about trailing security-class words breaking FIGI lookup. This is exactly the kind of semantic guidance agents need.

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

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

The description opens with concrete example phrasings that trigger the tool and states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly names the two supported types (company, drug) and what each returns, and differentiates from sibling tools by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource with clear differentiation from the many sibling research 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 gives an explicit when-to-use rule ('Use FIRST whenever you have a name but need an ID.') and explains when it does NOT assert a single answer (ambiguous bond issuer returns figi_candidates instead, which is 'the correct answer'). It also instructs on input format ('Pass the ENTITY NAME ONLY') and notes graceful degradation. This goes beyond implied usage to concrete, actionable routing.

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 false, so safety is clear. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density. This meaningfully extends 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?

Two sentences that front-load the core action and result. The example question adds flavor but is not essential. Could be slightly more concise, but overall efficiently communicates purpose and output.

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

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

No output schema, but the description explains the return format (ranked list with score, confidence, signal density). It covers purpose, input constraints (2-8 entities), and integration with ai_visibility_check. Some behavioral details like ordering or tie-breaking are missing, but sufficient for an aggregation 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%, so the baseline is 3. The description adds minimal parameter meaning beyond the schema (e.g., 'first entry treated as subject for narrative'). It does not elaborate on 'models' or '_apiKey' beyond schema descriptions, so no significant added value.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks them. It uses specific verbs ('Compare', 'Probes', 'ranks') and distinguishes from the sibling ai_visibility_check (single entity) and compare_entities (generic comparison without AI focus).

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 a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly differentiates from single-entity probing but does not explicitly state when not to use or name alternatives. The sibling list includes ai_visibility_check and compare_entities, which are related but unaddressed.

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 (readOnlyHint, idempotentHint, etc.), the description discloses latency (bundlephobia first measurement 5-30s), graceful degradation (sources_failed lists timeouts), and return format (summary block, advisories, links, alternatives). 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 detailed and well-organized, front-loading purpose and then details. It is slightly verbose but every sentence contributes value, 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 no output schema, the description fully explains return values (summary block, advisories, links, alternatives). It also covers limitations, partial failures, and default behavior, making it complete for its complexity.

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

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

Schema description coverage is 100% for both parameters. The description adds meaning: scoped packages accepted for 'package', and default behavior for 'version' (defaults to latest).

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb 'check', the resource 'npm package', and distinguishes from sibling tools by limiting to npm ecosystem v1.

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

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

Explicit when-to-use examples are given ('is X safe / popular / small' or 'what does adding lodash cost me'). It also specifies when not to use (non-npm packages) and directs to alternative ('fall under deps.dev:version 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?

Adds to annotations by stating return fields (title, description, date, NASA ID, media type, thumbnail URL) and the fact it requires no API key ('Keyless'). Annotations already declare read-only, idempotent, non-destructive behavior. No contradiction.

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

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

Two sentences, front-loaded with purpose. Second sentence combines usage hint and return info. Efficient but could be slightly more structured to separate return details.

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

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

For a simple search tool with 3 parameters and no output schema, description covers key aspects: scope, usage examples, return fields, and keyless access. Lacks details on pagination or error conditions, but is sufficient for straightforward use.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds 'Keyless' but that is about authentication, not parameter meaning. Baseline 3 is appropriate as description does not significantly add to 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?

Description clearly states it searches the NASA Image and Video Library for images/videos of any subject, with specific examples like planets and missions. The verb 'Search' and resource 'NASA Image and Video Library' are specific. It distinguishes itself from sibling tools by being a specialized image search tool.

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

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

Includes 'PREFER for' with concrete query examples, guiding appropriate use. Does not explicitly state when not to use or mention alternatives, but the context is clear given it's a niche tool among diverse siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), char cap (200K chars with truncation flag), and return format (passages with character offsets and similarity scores). 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?

Single paragraph with front-loaded purpose, no wasted words. Each sentence adds distinct value: purpose, usage guidance, pairing suggestion, technical details. Perfectly balanced for an AI agent to quickly parse.

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

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

With only three parameters and no output schema, the description covers all necessary aspects: what the tool does, when to use it, how it works internally (embeddings, windowing, truncation), and what output to expect (passages with offsets/scores). No gaps remain for an AI agent to infer.

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%, providing basic descriptions for all three parameters. The description enhances this with example queries for 'query' (e.g., 'supply-chain risk'), clarifies the max length for 'text' (200K chars), and specifies the default and range for 'limit' (1-20, default 5). While schema already covers structure, the description adds contextual value.

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

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

Description uses specific verb+resource: 'semantic search INSIDE a fetched record'. Provides concrete examples like 'SEC 10-K body, an article, a long tool result' and distinguishes from sibling tools by stating it saves context and returns passages with offsets.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also gives a clear alternative/partner tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This leaves no ambiguity about 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?

Annotations already indicate idempotentHint=true and readOnlyHint=false. The description adds essential behavioral details: authentication requirement, return value (subscription id), webhook auto-disable after 10 failures, and SMS rate limit (10/day). This enriches understanding 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 thorough and well-structured, starting with the core purpose, then prerequisites, then detailed type and delivery information. It is slightly long but every sentence adds value. No redundancy.

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

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

Given the tool's complexity (multiple subscription types and delivery channels) and no output schema, the description covers all critical aspects: creation behavior, authentication, type-specific parameters, delivery options, failure handling, and rate limits. It is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial value: it provides concrete examples for each type and its params (e.g., sec_8k with items codes, polymarket_edge with topic), and explains delivery channels with constraints (phone verification, webhook signing). This goes far beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the resource (subscription to event streams) and the action (create), and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts 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 includes important usage context: requires a Pipeworx OAuth account (anonymous and BYO cannot persist), and details delivery channel options. It does not explicitly contrast with sibling tools but the context is sufficient to infer when to use subscribe (for creation) versus list_subscriptions or unsubscribe.

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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns category-bucketed example questions with exact tool+argument shape, and mentions calling with no arguments or a topic. 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?

Description is a single dense paragraph with all key information front-loaded. It includes examples and details about output. Could be slightly more structured, but not overly verbose.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains purpose, usage, parameters, and return value (category-bucketed example questions with tool+argument shape).

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 has one optional parameter 'topic' with description. Description adds context: omitting topic gives full spread, passing topic focuses. Schema coverage is 100%, but description enriches meaning beyond schema.

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

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

The description states it is an onboarding entry point that returns category-bucketed example questions, distinguishing it from sibling tools like ask_pipeworx which handle actual queries. It clarifies the verb 'suggest questions' and resource 'Pipeworx 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when to use, though does not explicitly list when not to use or alternatives beyond implication.

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?

Description explains that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds valuable context beyond annotations, which indicate non-destructive and idempotent behavior. 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?

Two sentences with no wasted words. Front-loaded action and clear purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and side effects completely. Annotations support the description.

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

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

Single parameter 'id' is described as 'Subscription id (uuid) returned by subscribe,' which adds context beyond the schema's basic description. Schema coverage is 100%.

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

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

Description states 'Cancel a subscription by id,' which is a specific verb+resource. It clearly distinguishes 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?

Description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which is a key constraint. It does not explicitly mention when not to use, but the purpose is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds critical behavioral context: the two-path routing, the special meaning of 'could_not_verify' (check failed, not evidence), and 'unsupported' (no source found). It also discloses the return structure (verdict, actual value, citation, reasoning).

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

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

The description is longer than average but every sentence earns its place: trigger phrases, purpose, routing, return values, and a critical caveat about 'could_not_verify'. Information is front-loaded and logically ordered.

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

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

With no output schema, the description fully explains return values and the failure mode. It covers the complex routing, verdict types, and error semantics, making it complete for a verification tool of this complexity.

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

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

Schema description coverage is 100%, and the schema already fully describes both parameters (claim example, tolerance_pct range and override semantics). The description adds no new param-specific meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It lists explicit trigger phrases and distinguishes between financial and non-financial claims, separating it from sibling tools like ask_pipeworx or compare_entities.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic (SEC EDGAR for financial claims, grounded pipeline otherwise). It also implies when not to use (non-claim factual queries) and notes it replaces 4–6 sequential calls.

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