Mast Nasa

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: the default model is free, Anthropic requires a BYO API key with direct payment, and it discloses the return structure. This goes beyond just restating annotations.

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

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

The description is three sentences, front-loaded with the core action and output, and every sentence adds information. It efficiently covers purpose, model options, API key handling, return fields, and use cases without redundancy.

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

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

Given there is no output schema, the description appropriately explains the return format (per-model score, confidence, signals, raw_response, plus combined view). It also clarifies cost implications and supported models, making it self-sufficient for an agent to decide 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 baseline is 3. The description enriches parameters by explaining that `_apiKey` is passed straight through to Anthropic and that you pay for those calls, and that omitting models uses the free default. It also clarifies the meaning of 'probe' in the context of visibility scoring.

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

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

The description clearly states a specific action ('Probe one or more LLMs'), the resource (business/brand/product/topic), and the output (visibility score 0-100 per model). It distinguishes this tool from the sibling tools by focusing on LLM knowledge visibility scoring, not general search or research.

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

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

The description gives concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to probe Anthropic) and that the default model is free. However, it does not explicitly contrast with similar sibling tools like scan_competitor_ai_presence, so it stops short of providing exclusionary guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds context beyond those: it routes to one of 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier. It does not mention rate limits or auth, but no contradiction exists and the added behavior details are valuable.

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

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

The description is long but front-loaded with 'PREFER OVER WEB SEARCH' and each sentence serves a distinct purpose: scope, routing behavior, trigger phrases, examples, default positioning, and alternates. It is dense but not wasteful; slightly longer than strictly necessary but earns its length.

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

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

Given no output schema, the description compensates by explaining the return type (structured answer with citation URIs), scope (authoritative structured data), and escalation paths. It is complete enough to invoke correctly for the vast majority of factual questions, though it could mention edge cases like unsupported queries or result-size limits.

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

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

The input schema already documents the 'question' field and all aliases with 100% coverage, which sets a baseline of 3. The description adds sample questions and says the tool 'fills arguments' but does not provide deeper parameter semantics or formatting details beyond what the schema already gives.

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

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

The description clearly states a specific function: routes questions to the appropriate tool among thousands of sources and returns structured answers with stable citation URIs. It explicitly positions itself as the default factual-query entry point and distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and gives concrete trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), plus explicit escalation guidance to ask_pipeworx_grounded and deep_research. It also notes breaking-news routing, making when-to-use extremely 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?

The description discloses that candidate routing improvements are enabled live, results are compared against the stable router for merge decisions, and it is a full working router with no fallback. These are behavioral traits beyond the annotations, which only cover safety hints like read-only and idempotent.

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 focused sentences, each earning its place: identity, current state, usage, and reassurance. The description is detailed but not verbose, with key information 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?

Despite no output schema, the description sufficiently explains the tool's nature, current behavior, and relationship to the stable router. It clearly conveys that this is a functional experimental variant, making it complete 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 coverage is 100%, with all 6 parameters and aliases fully described. The description adds no parameter-specific meaning beyond saying 'same arguments', so the baseline score 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 the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing its experimental nature and live candidate routing improvements.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and provides context that the tool currently matches the stable version because no candidate is active. This gives clear when-to-use guidance and implies the alternative for non-experimental use.

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

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

Goes well beyond annotations by detailing the exact response structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerating all refusal reason values. It also discloses the extra LLM call cost and the extraction process. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

Dense but every sentence earns its place: purpose, mechanism, return format, usage conditions, and cost tradeoff. Front-loaded with the core value proposition, then structured logically. No redundant 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?

With no output schema, the description fully compensates by specifying the return object and all refusal reasons. It also covers use cases, routing context, and cost implications. This is complete for a complex tool.

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

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

Schema covers 100% of parameters with each alias described as 'Alias for question,' so the description adds no additional parameter semantics. Baseline 3 applies; no deduction needed.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's purpose. It distinguishes itself from ask_pipeworx by explaining it uses the same routing but extracts answers only from tool results, with explicit refusal modes. This is a specific verb+resource+differentiator.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It names ask_pipeworx as the alternative and includes a cost tradeoff (one extra LLM call). This satisfies both when-to-use and when-not-to-use.

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

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

Annotations already state read-only, idempotent, non-destructive. The description goes far beyond, disclosing fan-out logic, resolver confidence levels, parent-event extraction, news fallback behavior, low-confidence short-circuiting, closed-market statuses, wide-spread warnings, and cancellation-rule risk. This is exemplary transparency.

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

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

The description is long but highly structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence carries specific, actionable details. It is front-loaded with the core purpose. The length is justified by the tool's complexity, though it could be slightly more succinct without losing value.

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

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

With no output schema, the description must explain return values and behavior, and it does so thoroughly: result.market, result.analysis, result.evidence, market_match_confidence, parent_event, news fields, statuses, and safety mechanisms are all specified. For a tool of this complexity, the description is complete and self-sufficient.

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

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

Input schema has 100% parameter description coverage, so the baseline is 3. The description adds meaningful context beyond the schema, such as recommending include_raw=false for typical use and explaining how market format (slug/URL/question) is resolved. While not exhaustive, it enhances understanding of the parameters' practical effects.

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 clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via data pull), distinguishing it from sibling tools. The 'Use for' examples further crystallize the intended 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 explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides concrete examples. It also includes guidance like checking cancellation rules before sizing bets. However, it does not explicitly mention when not to use the tool or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds no behavioral disclosure. It does not mention that this is a raw MAST passthrough, response characteristics, or any operational caveats. The description remains silent on behavior 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 extremely short (six words), which makes it concise in length but not in substance. This is under-specification rather than efficient conciseness; it omits essential guidance and leaves the agent without adequate context.

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 a nested query object, an output schema, and a complex raw request interface, the description provides no overarching context. It fails to explain what CAOM is, the types of queries supported, or how the tool fits into the broader MAST ecosystem. The schema carries all the weight, which is insufficient for an agent to confidently invoke the tool.

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

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

The single parameter 'query' has a schema description ('Raw MAST request body (service + params)') that is 100% coverage. The tool description itself adds no parameter semantics, but the schema already explains the parameter structure, including an example with service and params. This meets the baseline for high schema coverage.

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

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

The description states 'Generic CAOM (Common Archive Observation Model) query,' identifying the resource (CAOM) and the action (query). However, it is vague, lacking specifics about what the query does, what it returns, or how it relates to sibling tools. It is not a tautology but offers minimal clarity about the tool's actual function.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or comparison to sibling tools like cone_search or mission_search. An agent would have no basis to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context without contradiction: it pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond the structured annotations.

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

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

The description is dense with useful trigger examples, data source details, and output behavior. It is slightly longer than the minimal viable description, but every sentence provides distinct value and it is front-loaded with usage triggers. No redundant or vague phrasing.

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

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

Even without an output schema, the description fully explains the return format (paired data + pipeworx:// citation URIs), data sources, sorting behavior, and constraints (2–5 entities). It is self-contained for an agent to select and invoke the tool 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% and both parameters have descriptions. The tool description adds value by explaining what each type retrieves (10-K financials vs FAERS/FDA/trial counts), which enriches the meaning of the 'type' parameter beyond the schema's enum listing.

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

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

The description clearly states a specific verb ('compare') and resource ('entities'), and provides a rich set of trigger phrases like 'X vs Y' and 'rank these companies'. It explicitly contrasts with sequential single-pack lookups, differentiating it from sibling tools such as entity_profile and lookup_name.

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

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

The description explicitly states when to use the tool ('when comparing entities', 'ALWAYS PREFER over sequential single-pack lookups') and provides examples of user intents. This gives clear usage guidance and directly names the alternative approach it replaces.

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

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

Annotations already declare the tool as read-only (readOnlyHint=true), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false), so the description does not need to repeat those. The description adds little beyond the resource name (MAST) and does not disclose additional behaviors like rate limits, pagination, or result ordering, but this is acceptable given the strong annotation coverage.

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

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

The description is a single, front-loaded sentence with no wasted words, making it highly concise and easily parseable. However, it is almost too terse, omitting useful context that could be added without bloating the description.

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 5 parameters, 2 required, and an output schema, this description is insufficient. It does not explain what MAST is, how to interpret the parameters, default behaviors (e.g., radius_arcmin default is in schema), or any other contextual clues needed for proper invocation. The description relies entirely on the schema and annotations, which are not fully populated.

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 only 40% (only mission and radius_arcmin have descriptions). The description does not compensate for the lack of parameter explanations; it merely repeats the coordinate parameters (RA, Dec) and gives no insight into limit, radius_arcmin, or the meaning of mission beyond what the schema already provides. Since coverage is low, the description needed to add more 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 performs a search on MAST around a central coordinate (RA, Dec), making the verb and resource explicit. It does not explicitly differentiate from sibling tools like mission_search or search_within, but the specific mention of MAST and cone search context gives reasonable clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of typical use cases, prerequisites, or situations where a different tool would be more appropriate, leaving the agent to infer usage from the name and description alone.

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 read-only/idempotent annotations, the description richly discloses behavior: account and paid-tier requirements, parallel decomposition, findings packet composition, gaps[] never invented, contradictions[] for standard/thorough, citation_uri resolvability, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is long but information-dense; it front-loads the account requirement and core differentiator. Each sentence covers a distinct aspect (alternatives, gaps, contradictions, citations, excerpting, latency) without redundancy. A slightly more structured layout (bullets) could improve readability, but the content is justified for the tool's complexity.

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

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

The description is exceptionally complete: it covers purpose, usage scenarios, alternatives, account restrictions, parameter semantics, return packet structure, citation behavior, limitation handling (gaps), and performance. Even without an output schema, it precisely describes what the user receives. This is as complete as one could expect for a research 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 both parameters have descriptions, which is a baseline of 3. The description adds practical meaning with example questions ('compare X and Y's regulatory + financial exposure') and further elaborates depth tiers' hop behavior, though much of this is already in the schema. Overall it adds value beyond the schema.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It clearly distinguishes from siblings by explicitly contrasting with ask_pipeworx and open-web search, and specifies the scope of the tool.

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

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

The description explicitly states when to use this tool: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides an account-requirement alternative: if not signed in, use ask_pipeworx.

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 useful behavioral context: the response includes full input schemas with curated examples and is ready to call directly without a second lookup. It does not contradict annotations, and these extra details go beyond 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?

The description is moderately sized and front-loaded with the core action ('Find tools by describing the data or task'). The domain list is verbose but informative, and the return format and usage hint each earn their place. No extraneous fluff.

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

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

Given no output schema, the description adequately explains the return value (top-N tools with names, descriptions, schemas) and when to use it. It does not mention pagination or error behavior, but these are not critical for a discovery tool. The coverage of input semantics and usage context is sufficient.

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

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

Schema description coverage is 100%, with each parameter fully described including aliases and examples. The description reinforces that the main input is a natural language description of a data/task, and mentions top-N results, but it doesn't materially add beyond the schema's explicit parameter docs. 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's purpose as finding/discovering tools by describing data or tasks, and explicitly distinguishes itself from data-search siblings by stating it returns tool schemas. It uses a specific verb-resource pair ('Find tools') and emphasizes the discovery role with examples of domains.

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

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

The description provides clear 'when to use' guidance: browse/search/look up/discover what tools exist, and explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies an alternative (direct answer tools) but does not name specific sibling tools, so it lacks explicit when-not/alternatives.

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

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

The description goes well beyond the annotations (readOnly, idempotent, openWorld) by disclosing the fan-out architecture across SEC EDGAR, XBRL, USPTO, news, and GLEIF, listing exact return fields, noting the patents API sunset with soft-fail behavior, and describing GDELT→GNews fallback. This is rich behavioral context.

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

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

The description is long but information-dense, starting with user-phrasing examples to capture intent and then systematically covering functionality, return data, and limitations. Every sentence adds substance, though it could be slightly more scannable with line breaks.

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 enumerates all return components (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI), sources, fallbacks, and limitations. This gives a complete picture for an agent to invoke the tool and interpret results correctly.

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

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

The input schema already covers both parameters thoroughly: 'type' has enum description, 'value' explains ticker/CIK formats and name limitation. The description repeats these details and adds example values ('AAPL', '0000320193'), but this is marginal beyond the schema's existing clarity. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company and provides example user phrasings ('Tell me about X', 'research Acme'). It distinguishes from single-source lookups by emphasizing 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions resolve_entity for name-only inputs, differentiating it well.

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

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

The description explicitly says when to use the tool: 'when the user asks for a holistic view' and instructs to prefer it over chaining single-source tools. It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name),' providing a direct alternative.

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

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

Annotations already indicate destructiveHint and idempotentHint. The description adds specific context: it deletes a previously stored memory by key, and explains use cases like clearing sensitive data. This goes beyond the raw hints by specifying what is affected.

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

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

The description is two sentences, front-loaded with the action, and every clause adds value: the operation, use cases, and related tools. 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 one-parameter tool with no output schema, the description covers purpose, usage timing, and relationships to sibling tools. Combined with the annotations, it is complete for effective agent 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?

The input schema provides 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'). The description adds no additional parameter meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Delete a previously stored memory by key.' It clearly distinguishes itself from sibling tools by naming the action (delete) and the complementary tools 'remember' and 'recall'.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember' and 'recall,' which implies alternatives, although it does not explicitly state 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 already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits a text blob. This goes beyond the annotations without contradicting them, though it could mention edge cases like invalid URLs or network failures.

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

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

The description is appropriately concise and front-loaded, starting with the action and purpose. Every sentence earns its place: process, output, and use cases. There is no filler or redundancy.

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

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

For a simple read-only tool with clear annotations and fully described parameters, the description is complete. It explains the input (any URL), the process, the output format, and typical use cases, leaving no critical gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significantly to parameter meaning; it mentions 'any URL' but the schema already fully documents 'url' and 'max_links'. No additional semantic value is 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 specific action ('Generate a production-ready llms.txt file for any URL') and the exact output format (standard llms.txt markdown). It also names the target resource (AI crawlers) and distinguishes itself from sibling tools by focusing on llms.txt generation, with use cases like auditing competitors.

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

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

The description provides clear use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context by listing the exact fields returned and clarifying that it only includes active subscriptions by default, which is useful behavioral detail beyond the structured annotations.

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

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

Two sentences: the first states the core function, the second lists return fields and usage guidance. No fluff, fully front-loaded, and every sentence earns its place.

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

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

For a simple list tool with one optional parameter and rich annotations, the description fully covers return fields and intended usage. No output schema exists, so listing the return fields is essential and done well.

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 single parameter include_inactive is fully described in the schema (100% coverage), so the description doesn't need to add much. The description's mention of 'active subscriptions' aligns with the schema but doesn't enrich parameter semantics further; baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, which is a specific verb+resource. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing, and enumerates the returned fields.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and ties it to subscription management workflows.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive, which covers the safety profile. However, the description adds no additional behavioral context, such as what happens when a name is not found, whether multiple results can be returned, or any rate limits. Given the annotations, a low score is warranted because the description does nothing to enrich the behavioral picture.

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

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

The description is a single, concise sentence: 'Resolve target name → coords.' It is front-loaded with the verb and resource, contains no filler, and is appropriately sized for a simple tool with one parameter.

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

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

The tool is very simple (one parameter, read-only, has output schema), and the annotations are rich, which lowers the burden on the description. However, the description still fails to mention any details about the output format, error handling, or coordinate system, leaving some gaps. It is minimally viable but not comprehensive.

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

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

The input schema has zero description coverage for the 'name' parameter. The description's phrase 'target name' adds minimal clarification, effectively restating the parameter name without explaining format, domain, or valid values. The examples in the schema do some work, but the description fails to compensate for the missing parameter documentation.

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

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

The description clearly states the action ('Resolve') and the resource ('target name → coords'), which is specific and unambiguous. However, it does not distinguish this tool from sibling tools like 'resolve_entity' that might perform a similar function, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The only implied usage is from the description itself, which is minimal. Sibling tools suggest there are competing similar tools, but no differentiation is offered.

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, covering the safety profile. The description adds 'arbitrary criteria,' indicating flexible filtering, which is a useful behavioral cue. However, it doesn't go beyond what schema and annotations already convey, and it doesn't mention pagination or data source specifics.

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

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

A single sentence that is front-loaded with the core action and scope. Every word earns its place, and the structure is immediately understandable. It's concise without being under-specified to the point of confusion.

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 search tool with a rich input schema and output schema, the description is largely complete. It explains the mission-scoped nature and arbitrary criteria, while annotations and schemas cover safety and parameter details. The only missing element is explicit usage guidance, but that is not essential for understanding the tool's function.

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 67% coverage (mission and criteria described; limit missing). The description's 'arbitrary criteria' adds semantic value to the criteria parameter, explaining it's a flexible object of filter columns/values. This compensates for some of the gap, but limit remains undescribed.

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 'Mission-scoped search with arbitrary criteria' clearly identifies the action (search) and the resource (mission data), and 'mission-scoped' differentiates it from spatially-oriented siblings like cone_search. However, it does not explicitly name alternatives or contrast with other search tools, so it doesn't fully earn a 5.

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 usage context is implied: use when you need to search within a specific mission with flexible criteria. The description does not provide explicit when/when-not guidance or mention alternative tools like cone_search or search_within. This is an implied-usage scenario, not a clear guideline.

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

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

The description adds substantial behavioral context beyond the boolean annotations: the claim_token lifecycle (filing returns a token; passing it back retrieves status), rate limiting (5 per identifier per day), cost (free, no quota), and operational details (team reads digests daily). It also discloses the non-read-only nature by explaining the submission side effect.

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

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

Although the description is long, every sentence earns its place: purpose, trigger conditions, scope boundary, content policy, claim_token mechanics, rate limit, and cost. It is front-loaded with the core purpose and contains no filler, making it dense yet 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?

The tool has a nuanced claim_token workflow and rate-limiting behavior, all fully explained in the description. Since there is no output schema, the description appropriately covers what filing returns ('claim_token') and how to use it to read status/resolution. Scope, exclusions, and practical operation are all addressed.

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 meaningful usage constraints for the message field ('don't paste the end-user's prompt', 'describe in terms of Pipeworx tools/packs') and clarifies the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which enriches the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by restricting scope to 'tools served by this Pipeworx connection' and contrasting with other MCP servers. Enumerating feedback categories (bug, feature, data_gap, praise) removes any 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?

Explicit when-to-use triggers are provided ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'), along with a clear exclusion (tools from other MCP servers) and a method for verifying scope ('Pipeworx tool names are the ones this connection lists'). It also gives content guidance ('don't paste the end-user's prompt'), making selection unambiguous.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on the window. This gives the agent a clear picture of data provenance and freshness, though exact response formatting is not detailed.

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 and front-loaded: it starts with the core output, then provides use cases, then adds provenance/caching details. Every sentence contributes meaningful information without redundancy or filler.

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

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

For a simple one-parameter tool with no output schema, the description is complete. It explains what is returned, the available windows, why the data exists, its privacy characteristics, and cache behavior. This is sufficient for an agent to invoke the tool correctly and interpret results.

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

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

The schema covers 100% of the parameter documentation, including the enum values and their meaning (shorter vs. longer windows). The description only repeats the window options without adding new semantic detail, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does with a specific verb and resource: "Returns the top tools, top packs, and total call volume" for Pipeworx. It also distinguishes itself from siblings by focusing on cross-agent trending signals rather than general search or discovery.

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

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

The description provides explicit use cases in a numbered list: discovering hot data sources, confirming canonical tools, and checking alignment with other agents. It also explains how to choose between time windows. It does not explicitly name alternatives or state when not to use the tool, so it falls just short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds deep behavioral context: placeholder filtering, similarity thresholds, null signals, fill check pricing, and the 'do not trade' rule. This far exceeds the annotation coverage and provides actionable constraints on result interpretation.

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

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

The description is long but well-structured, with each section (modes, semantic anchor, partition filter, fill check) earning its place. It is front-loaded with the core purpose and mode selection. Slightly verbose, but given the tool's complexity, this is appropriate; only minor redundancy exists (e.g., repeating 'call with no args' context).

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 response format is fully described (opportunities[] fields, partition_check fields). It covers all operational details: modes, filters, edge cases, and when to avoid trading. Completeness is high for a tool with two optional params and a complex algorithmic behavior.

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%, yet the description enriches both params with concrete examples (event slugs, topic seed questions) and clarifies behavior ('Full Polymarket URLs also accepted'). It explains that event and topic are mutually exclusive modes with distinct scanning strategies, adding value 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from siblings like polymarket_edges (which likely focuses on edges) and polymarket_fill_risk (custom sizing), by focusing on arbitrage detection mechanics.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan...' then distinguishes event vs topic modes with recommendations ('event (recommended for a specific market)' and 'topic (for cross-event scanning)'). It even provides an alternative tool ('For custom sizing use polymarket_fill_risk') and a caution against trading when realizable edge is ≤0, making the usage context exceptionally 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?

Despite annotations already indicating readOnly/idempotent/non-destructive behavior, the description adds substantial behavioral context: edge_pp_net is net of slippage, kelly_fraction is capped at 0.25, a 24h-move warning is provided, and the placeholder-slug filter and partition_overround bias-correction are described. This goes far beyond the annotation safety profile.

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

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

The description is verbose but well-structured with sections for model families, response top-level, knobs, and diagnostics. Every sentence adds technical detail necessary for a complex 9-parameter tool with no output schema, though it could be slightly more streamlined. The front-loading of the core purpose is 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 absence of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), the behavior of each model family, and the impact of knobs on filtering. It also includes operational details like 1h KV caching and edge-case handling (placeholder-slug filters), making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in context, and by clarifying slippage assumptions ('Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp per trade'). This enhances understanding beyond the per-parameter 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes itself from siblings by detailing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the response segmentation, making it highly specific.

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

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

The description explicitly positions the tool for agents discovering betting opportunities without paging hundreds of markets, and explains the tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) that filter unrealizable edges. It also includes a caveat about Fed bets being unreliable, providing clear usage context, though it does not explicitly name alternative sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: snapshot write-on-cache-miss behavior, gaps in snapshot_dates, 60-day TTL limits, and that decay numbers derive from daily closes not intraday. This goes far beyond annotations and fully discloses data caveats.

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 Args, RESPONSE, and LIMITS sections. Every sentence adds necessary context for a telemetry tool with no output schema. It is dense but each component (tracked[], expired[], snapshot_dates[], and limits) earns its place and is front-loaded with the core 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 the tool's complexity—multiple response components, time-series semantics, and snapshot edge cases—the description is remarkably complete. It explains the response format in detail, including trend labels, decay computation, expired opportunities, lifespan_days, and snapshot-date gaps. The lack of an output schema is fully compensated by this 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?

Schema description coverage is 100% for both parameters, so baseline is 3. The description only repeats what the schema already provides for days and window (defaults, clamping, allowed values) without adding extra semantic depth. It does clarify that 'window' refers to a snapshot family, but this is essentially identical to the schema text.

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 provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This specific purpose differentiates it from the sibling polymarket_edges (which likely provides current edges) by focusing on historical tracking and decay.

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 conveys when to use the tool: when you care about edge age and persistence ('a fresh wide edge and a 3-week-old wide edge are different trades'). It lacks an explicit 'use this instead of X' statement, but the contrast with current-edge tools and the snapshot-based methodology imply the appropriate context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it details what happens in single-market vs basket mode, lists return fields like top_of_book and vwap_fill_price, warns that partial basket fills convert an arb into an unhedged directional position, and explains the verdict categories. This far exceeds the annotation baseline, with no contradictions.

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

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

Though long, the description is highly efficient and well-structured: it opens with the core purpose, then clearly separates SINGLE-MARKET and BASKET behavior, lists return fields compactly, and ends with concrete usage guidance. Every sentence earns its place, and the density is justified given the tool's complexity.

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

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

With no output schema, the description compensates by enumerating many return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It covers dependencies (requires market or event), defaults, and the risk rationale, making it a complete guide for invocation.

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

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

Schema coverage is 100%, but the description adds crucial depth: it clarifies that size_usd means 'max spend' for buys, 'target proceeds' for sells in single-market mode, and 'settlement notional' (shares per leg) in basket mode. It also explains the side parameter's valid values per mode and the auto-detection logic for basket mode. This is a strong enrichment beyond the schema.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and names the sibling tools it complements (polymarket_arbitrage, polymarket_edges), making its unique role obvious.

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

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

The description provides explicit usage context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It mentions the alternatives (arbitrage and edges tools) and implies when not to use (below the threshold), giving clear guidance for selection.

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

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

The description adds substantial behavioral context beyond the annotations. It details the response structure (leg-by-leg prices, spread[]), safety fields (compatibility_warning, temporal_alignment), and the meaning of skipped_cross_type/subtype. It also discloses limitations (most pre-mapped topics are not tradeable). The annotations already declare read-only/idempotent, and the description enriches this 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 detailed and somewhat lengthy, but every sentence contributes unique information about modes, response fields, warnings, and limitations. It is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). While not a model of brevity, it is appropriately sized for the tool's complexity.

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

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

Given that there is no output schema, the description fully covers what the agent should expect: leg-by-leg prices, spread in percentage points, compatibility warnings, and temporal alignment. It addresses edge cases (non-equivalent bet shapes, unrelated events) and explains the skip counters. This is comprehensive for a tool with three optional parameters.

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

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

Schema coverage is 100%, so parameters have individual descriptions. The tool description adds interaction semantics: it explains that topic is for pre-mapped shortcuts, while kalshi_event_ticker and polymarket_event_slug override the mapped side. This clarifies the relationship between parameters, which is valuable 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 the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread), the resources (two venues), and the scope (same resolving question). It distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing the cross-venue nature and the two modes of operation.

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

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

The description provides explicit usage context: it explains two modes (topic shortcuts vs explicit ticker/slug), and gives warnings about when the tool is not applicable (non-equivalent bet shapes, temporal misalignment). It also cautions that most pre-mapped topics return compatibility_warning, setting realistic expectations. However, it does not explicitly name alternative sibling tools to use instead, so it falls short of a 5.

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

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

Annotations already establish readOnly and idempotent safety. The description adds value by disclosing scoping behavior ('Scoped to your identifier...') and the two modes of operation (regular retrieval vs. listing all keys). It doesn't cover missing-key behavior, but that minor gap is offset by annotation coverage.

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

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

The description is four tightly written sentences, each contributing essential information: main function, use case, scoping, and pairing with sibling tools. No filler or redundancy.

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

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

For a tool with one optional parameter and no output schema, this description is nearly complete. It covers purpose, usage context, scoping, and sibling relationships. The only missing detail is what happens when a key doesn't exist, but this is a minor omission given the simplicity of 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 coverage is 100% and the parameter description already states 'omit to list all keys'. The description reinforces this with practical examples of what keys represent ('target ticker, an address, prior research notes'), but does not add novel 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 opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings by naming remember and forget as the counterpart operations, and provides concrete examples (user's target ticker, address, prior research notes).

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 the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names how to pair it with remember (save) and forget (delete), which are direct 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?

Beyond the annotations, the description discloses that each alert carries 'source, citation_uri (pipeworx:// when available), and the raw event payload.' It explains the mark_read side effect—'flag returned events read so the next call only shows newer ones'—and mentions the same feed is publicly accessible, adding valuable behavioral context.

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

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

The description is three sentences, front-loaded with the core purpose, followed by return structure and usage notes. Every sentence earns its place, with no redundancy or fluff, making it an exemplary concise description.

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

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

Even without an output schema, the description explains the return fields and the mark_read state behavior. It also addresses polling safety and gives an alternative access URL, covering the tool's operational context well for a 5-parameter read-oriented 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%, so the baseline is 3. The description adds an example filter type ('sec_8k') and ties mark_read to future call behavior, slightly enriching parameter understanding, while leaving limit and unread_only to the schema, which is already explicit.

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: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts the evaluator has written to your persisted feed.' It names a specific resource and action, and distinguishes this from any sibling by focusing on alerts/feed retrieval.

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

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

The description provides clear usage context: filtering by 'type' and 'since', the effect of 'mark_read' on subsequent calls, and that polling works fine. It does not explicitly name alternative sibling tools or state when not to use this tool, but it offers enough context for appropriate use.

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

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

Despite having readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: it details fan-out to multiple sources, fallback logic (GDELT→GNews), soft-failure for patents, and accepted date formats. It also discloses the return structure, going 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 dense but every sentence earns its place: examples front-load purpose, technical details explain sources and fallbacks, and the alternative tool is clearly pointed out. It is well-structured and avoids redundancy.

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

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

There is no output schema, so the description appropriately explains the return format (changes[], total_changes, citation URIs). It also covers source behaviors, edge cases (patent soft-fail), and provides a comparison to an alternative tool, making it complete for a complex operation.

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

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

Schema coverage is 100%, and the description largely repeats parameter details already in the schema (e.g., since accepts ISO or relative shorthand, value is ticker/CIK). The description provides examples but adds minimal new parameter-level meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: "change feed for a company in the last N days/weeks/months." It also differentiates from sibling tools by explicitly recommending entity_profile for static profiles, making the purpose unambiguous.

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

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

The description provides explicit usage context with example questions like "What's new with X" and "latest on Y." It also names an alternative tool (entity_profile) and defines when to use it, giving clear when/when-not guidance.

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

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

Adds behavioral context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and it is a key-value store. Annotations already indicate non-read-only, non-destructive, idempotent, and the description aligns 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?

Three sentences with no redundant content. Front-loaded with the core purpose, then usage, then storage specifics and sibling links. Every sentence earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers purpose, when-to-use, persistence behavior, scoping, and companion tools. It is complete for the tool's complexity without needing further detail.

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

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

Schema coverage is 100% with clear descriptions for both 'key' and 'value'. The description adds examples (resolved ticker, user preference) but these largely mirror the schema's examples (target_ticker, user_preference). No additional parameter-specific meaning is provided beyond what the schema already 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?

Clearly states the primary function with a specific verb ('Save data') and resource (key-value memory), and distinguishes itself from siblings by explicitly pairing with recall (retrieve) and forget (delete). The scope is concrete: conversational and cross-session persistence.

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 with concrete examples (resolved ticker, target address, user preference) and explicitly names alternatives (recall, forget), telling the agent exactly 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?

Beyond the read-only, idempotent annotations, the description reveals that GLEIF/OpenFIGI enrichment degrades gracefully, still returning EDGAR identifiers when external sources are unavailable. It also discloses that unresolved identifiers are explicitly stated under `unresolved` rather than omitted, and that each call cascades through multiple lookup endpoints.

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

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

The description is dense but every sentence earns its place—examples, supported types, behavioral notes, and failure handling. Despite being longer than average, it is well-structured and front-loaded with examples.

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 covers purpose, input variations, sources, fallback behavior, and how unresolved results are handled. It gives an agent sufficient context to invoke and interpret results effectively.

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

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

The schema already documents both parameters completely with examples and accepted formats. The description adds minimal new parameter semantics, mostly repeating schema content; the only slight extra is the context about FIGI resolution when a ticker is implied.

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 queries and explicitly states its function: resolving a name to canonical/official identifiers other tools require as input. It distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID,' which clearly differentiates it 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?

The description explicitly directs usage with 'Use FIRST whenever you have a name but need an ID,' and notes it replaces 2-3 manual lookups. It enumerates supported entity types and input formats, providing clear when-to-use context.

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

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

The description goes beyond annotations by detailing the probing mechanism, ranking by score, and return format (ranked list with score, confidence, signal density). It also mentions the first entity is treated as 'subject', adding context that is not in annotations or schema. No contradiction with readOnly/openWorld/idempotent hints.

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

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

The description is four concise sentences, each adding value: purpose, mechanism, use case, and output. No redundant phrases or repeated schema details.

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

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

The description is complete for a tool with no output schema: it states the return format, use case, and how the tool works. Combined with strong annotations (readOnly, openWorld, idempotent) and full schema parameter descriptions, the context is fully covered.

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 meaningful parameter semantics by explaining the first entity is the 'subject' and the rest are competitors, which is not in the schema. It also gives a concrete example of context usage, though it doesn't elaborate on models or _apiKey beyond what the schema already states.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verbs like 'Compare' and 'Probes'. It distinguishes itself from sibling ai_visibility_check by explicitly mentioning it probes each entity with that tool, clarifying it is a multi-entity comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example query, implying when to use it. It references ai_visibility_check as the probe, hinting at the alternative for single-entity checks, but does not explicitly state exclusions or name other alternatives like compare_entities.

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 richly discloses behavior beyond the annotations: it details what data is returned (summary block, per-advisory details, links, alternatives), explains partial failure behavior, notes that bundlephobia first measurement can take 5-30s, and specifies the ecosystem limitation. This greatly exceeds the annotation hints (readOnly, idempotent, non-destructive) and provides actionable operational context.

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

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

The description is longer than the calibration examples, but it is information-dense and each phrase adds value: purpose, use case, return payload, limitations, and failure mode. The structure is logical and front-loaded with the core purpose. Slightly verbose for a tool description, but appropriate for the tool's complexity.

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

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

With no output schema, the description fully explains the return structure, including the summary block fields, per-advisory detail, links, and alternative versions. It also covers operational caveats like partial failures and timeout behavior, making it complete for an agent to use the tool effectively in a complex scenario.

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 parameters are already well-defined in the schema. The description adds a few semantic hints, such as the npm-ecosystem scope and that version defaults to latest, but these are already in the schema. It does not materially extend parameter understanding beyond the schema.

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

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

The description states a clear, specific purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It names the exact resources and data points, and it is clearly distinct from sibling tools that focus on searches, visibility, or entity resolution. The verb 'scan' and the resource 'dependency' are well-defined.

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

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

The description explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion/alternative: for PyPI/Maven/Cargo/Go, use deps.dev:version directly. This gives clear decision guidance 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 already indicate readOnlyHint=true and destructiveHint=false, and the description complements this with technical behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and truncation flagging over 200K chars. It also clarifies output structure (offsets, similarity scores) which is not in 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?

The description is front-loaded with the core purpose, then quickly covers usage scenarios, technical details, and limitations in a dense but well-organized way. Every sentence provides actionable value, and there is no filler. Length is appropriate for the complexity of the tool.

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

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

The description fully covers what the agent needs to know: input expectations, output format (passages with offsets and scores), performance cap, truncation behavior, and integration with a sibling tool. Since there is no output schema, this textual explanation is crucial and complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: 'text' is described as 'the text you already pulled (e.g. a SEC 10-K body...)', 'query' gets natural-language examples, and 'limit' is implied via 'top-N passages.' It enriches parameter understanding without being redundant.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by emphasizing it works on already-fetched text and explicitly pairs with ask_pipeworx_grounded for the fetch-then-ground workflow. This is unambiguous and removes any confusion about 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?

Explicitly specifies when to use: 'Use when the record is too big to cram into the prompt.' It also provides a concrete alternative workflow with ask_pipeworx_grounded, explains what it returns (passages with offsets/scores), and notes the 200K char cap with truncation. This gives clear contextual guidance for agent decision-making.

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?

Discloses significant behavior beyond annotations: OAuth requirement, SMS phone verification and 10/day cap, webhook auto-disable after 10 failed runs, and one-time signing secret. No contradictions with annotations; adds operational details that aid invocation.

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

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

The description is dense but well-structured: purpose first, then auth requirement, type configurations, and delivery channels. Every sentence carries meaningful information; no filler.

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

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

Without an output schema, the description still states the return value (subscription id). It covers all supported types, delivery options, constraints, and verification steps, making it self-sufficient for a complex nested-parameter 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?

Although schema coverage is 100%, the description enriches each parameter with concrete examples (e.g., items:["5.02"] for officer changes), delivery validation rules, and webhook signing details. This fills in real-world usage nuances beyond the schema.

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

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

The description uses a specific verb ('Create') and resource ('subscription to a live-data event stream'), clearly stating what the tool does and that it returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by emphasizing reactive monitoring setup.

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 prerequisites (OAuth account required; anonymous/BYO cannot persist subscriptions) and channel guidance (feed always on vs optional email/sms, with consumption via recent_alerts). Lacks direct alternatives, but the when-not-to-use is clear from the auth restriction.

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 context beyond the annotations by explaining it 'draws from the live catalog of thousands of tools' and returns 'each with the exact tool + argument shape'. Since annotations already declare read-only and non-destructive, this extra context about output composition is valuable, though it does not cover edge cases like invalid topics.

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

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

The description is a single dense sentence that enumerates many example user queries up front, which is somewhat redundant but helps the agent recognize intents. It front-loads the purpose and packs useful details, making it efficient despite the verbosity.

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

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

The tool has only one optional parameter and no output schema, yet the description covers the return structure (category-bucketed example questions), the categories, the inclusion of tool and argument shape, and the optional focus behavior. This is complete for an agent to invoke it correctly.

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

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

The schema already has 100% coverage with a detailed description for `topic`, listing the allowed values and the omit-for-full-spread behavior. The description repeats similar information ('Call with no arguments for the full spread, or pass `topic`... to focus') without adding new semantics, 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 purpose as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses specific verbs ('Returns') and identifies the resource ('example questions') while distinguishing its role from sibling tools by positioning it as the first stop for new agents.

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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing a clear when-to-use directive. It also mentions learning how to call meta-tools, but it does not explicitly name alternatives or exclusions, so it stops short of full guidance.

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

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

Beyond annotations (readOnlyHint false, destructiveHint false), the description adds crucial behavior: ownership enforcement, soft-deactivation (row not deleted), and link to recent_alerts for historical events. This gives the agent a clear model of side effects 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?

Three short sentences, front-loaded with the core purpose. Every sentence adds value: purpose, ownership, and deactivation behavior. No fluff.

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

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

For a tool with one parameter and no output schema, the description covers the action, constraint, and post-state behavior, including a pointer to recent_alerts. It is fully 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?

The schema already covers the single `id` parameter fully. The description adds that the id must be one of the user's own subscriptions, providing a meaningful constraint beyond the schema's type and source description.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource combination that clearly distinguishes this from siblings like subscribe and list_subscriptions. It unambiguously states the action and target.

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

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

It provides clear context that this tool cancels subscriptions and enforces ownership, effectively telling the agent when it applies (your own subscriptions). It does not explicitly name alternatives or exclusions, so it doesn't reach the top score.

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

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

Annotations already mark it read-only and non-destructive, but the description adds crucial behavior: the meaning of could_not_verify vs unsupported, noting could_not_verify is not evidence and must not be presented as such. It also discloses that outputs include a verdict, grounded/structured actual value, and citation, and that tolerance_pct overrides claim-wording defaults.

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?

While long, the description is front-loaded with the core purpose and use case, and every sentence adds value—including error semantics and parameter tuning. It is dense and structured with an 'IMPORTANT for callers' callout, though it could be trimmed slightly.

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

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

Without an output schema, the description fully covers return values (verdict enum, actual value, citation, reasoning) and explains failure modes (could_not_verify carries verification_error, unsupported means no source). The tool's complexity justifies the thoroughness, and no critical aspect 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 input schema already describes both parameters (100% coverage), and the description adds meaningful guidance: tolerance_pct can be set to 1–2 for hallucination detection and defaults to the claim wording capped at 5. It also clarifies the claim parameter with realistic examples.

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 explicit natural-language phrases and states 'natural-language claim verification against authoritative sources.' It clearly defines the tool's scope (financial vs. other claims) and distinguishes it from generic search/ask tools by framing it as fact-checking with a verdict.

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 instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' and clarifies that financial claims go through the structured EDGAR/XBRL path while other claims fall through to a grounded pipeline. It also notes it replaces 4–6 sequential calls, signaling when to prefer it over multi-step workflows.

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