Mast Nasa

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

The description adds significant behavioral context beyond annotations: it explains the default model, the need for an API key for Anthropic (with cost implications), the return structure (per-model score, confidence, signals, raw_response + combined view), and the open-world aspect (probing external LLMs). No contradictions with annotations.

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

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

The description is three sentences: first sentence defines action and output, second provides essential setup details, third lists use cases. Efficient, front-loaded, and every sentence earns its place. No unnecessary words.

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

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

Given the tool has 4 parameters and no output schema, the description is quite complete: it explains default vs. optional models, API key necessity, return format, and use cases. It could mention error handling or rate limits, but for a simple probing tool this 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%, so the schema already documents parameters well. The description adds value by explaining the default model for the 'models' parameter, the role of '_apiKey' (pass-through to Anthropic, user pays), and the disambiguation purpose of 'context'. This goes beyond mere schema repetition.

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

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

The description clearly states the verb 'probe', the resource 'LLMs for knowledge about an entity', and the output 'score visibility (0-100) per model'. It distinguishes from siblings by specifying use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', which are distinct from other 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 indicates when to use this tool: for probing LLM knowledge. It mentions the default model and optional Anthropic model with an API key, but does not explicitly state when not to use it or compare with alternatives. However, the clarity of purpose implicitly guides usage.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds context about routing to many tools, returning structured answers with stable citation URIs, and being a single fast call. 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 relatively long but front-loaded with key guidance and examples. Every sentence adds value. Could be slightly more concise by reducing repetition, but overall well-structured.

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

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

Given no output schema and multiple params, the description covers purpose, usage triggers, behavioral constraints, citation format, and when to use alternatives. It provides sufficient context for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with aliases all described. Description gives examples but does not add new semantic info beyond the schema. 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 specifies that this tool answers factual questions by routing to a large set of structured data sources (4,770 tools across 1,241 sources) and returns answers with citations. It 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?

Explicit usage guidelines: prefer over web search, use for factual queries with specific trigger phrases ('what is', 'look up'), and step up to alternatives for hallucination-resistant or broad questions. Provides concrete examples.

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

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

Describes the internal routing, data fetching, and extraction logic. Discloses additional LLM call cost. Return format with success/refusal details is fully specified. Annotations (readOnly, idempotent, non-destructive) are consistent and complemented.

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

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

Description is one focused paragraph, front-loaded with purpose and key differentiator. Every sentence adds value 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?

Completely covers purpose, mechanism, return format, use cases, cost, and comparison with sibling. No output schema needed due to clear textual description of response structure.

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 well-described as aliases for 'question'. Description adds no extra semantic detail beyond the schema, but schema already suffices. 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?

Clearly defines the tool as hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling 'ask_pipeworx' by specifying extraction behavior and preference for casual lookups.

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

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

Explicitly states when to use: when answers will be quoted/cited/acted on and agent must not invent facts. Also advises preferring ask_pipeworx for casual lookups, providing clear guidance.

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

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

The description thoroughly discloses behavioral traits beyond annotations, including market resolution, classification, fan-out, low-confidence handling, closed market behavior, wide-spread warnings, resolution-rule risk, and parent event extraction. No contradictions with annotations (readOnlyHint, etc.) are present.

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

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

The description is very long and detailed, covering many edge cases and examples. While all information is valuable, it lacks conciseness and could be more structured. The first sentence is a good summary, but the overall length may overwhelm an agent.

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

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

Given the complexity of the tool and the absence of an output schema, the description is remarkably complete. It explains input types, behavior, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. No gaps are evident.

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%, but the description adds significant meaning: it details the market parameter as accepting slug, URL, or question text; explains depth (quick vs thorough) and include_raw with usage rationale and size implications. This enriches understanding beyond the basic 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 researches a Polymarket bet by pulling Pipeworx data, specifying the verb 'research' and the resource 'Polymarket bet'. It provides usage examples ('should I bet on X') that help distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage, though explicit differentiation is not given.

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 for should I bet on X, what does the data say about Y, or is there edge in Z'). It does not mention when not to use it or suggest alternatives, but the clear use cases provide sufficient guidance for an AI agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds no additional behavioral context beyond 'query', providing minimal value.

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 short but under-specifies the tool. Conciseness requires informative brevity, not just brevity. This is inadequate.

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 completely inadequate for a tool with a complex nested parameter. It does not explain CAOM, how to construct queries, or expected output, despite having an output schema.

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

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

Schema coverage is 100% for the single 'query' parameter, described as 'Raw MAST request body (service + params).' The description does not add further meaning; 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 'Generic CAOM (Common Archive Observation Model) query' is vague. It states it's a query but doesn't specify what it queries or what it returns. It doesn't distinguish from sibling tools like cone_search or mission_search.

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 on when to use this tool vs alternatives. The description lacks context, prerequisites, or when-not-to-use advice.

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 detailed behavioral traits including data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, result sorting, and output format (paired data with citation URIs). Annotations confirm safety, and description adds substantial 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 somewhat long but efficiently conveys all necessary information. Front-loaded with purpose and examples. Every sentence adds value, though slight trimming possible.

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 2 parameters and no output schema, the description fully explains input semantics, behavior for both types, sorting, and output characteristics (paired data, citation URIs). Covers edge cases like off-calendar fiscal years.

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 provides rich semantics: explains what each 'type' fetches, gives examples for 'values' parameter, and clarifies expected input formats (tickers/CIKs for company, names for drug).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs with specific example queries. It distinguishes from sibling tools by explicitly stating preference over sequential lookups.

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

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

Provides explicit when-to-use guidance for comparison queries and segmentation by entity type. Lacks explicit when-not-to-use but strong contextual guidance is present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds no new behavioral context. It does not contradict annotations.

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

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

The description is extremely brief (one sentence) and to the point. It is not verbose, but could be more structured.

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

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

Despite having an output schema, the description does not explain the behavior for parameters like 'limit' or 'radius_arcmin'. It is incomplete for a tool with 5 parameters.

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

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

Schema description coverage is 40%, yet the description adds no parameter explanations. It relies on examples in the schema, but fails to compensate for missing 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 specifies a clear verb ('Search') and resource ('MAST') with geographical parameters ('RA, Dec'). It is specific but does not differentiate from sibling tools like 'search_within'.

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 on when to use this tool versus alternatives. No exclusions, prerequisites, or examples of when not to use it.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the output structure (evidence, confidence, source, gaps[]), parallelism, time expectations (15-60s), and that it never invents answers. It also warns about empty gaps for non-structured 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 thorough but slightly verbose; however, every sentence adds value. It front-loads critical information (account required, alternative for non-signed-in users). Could be slightly more concise but still well-structured.

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

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

Given the tool's complexity, the description is exceptionally complete. It covers input requirements, output expectations, limitations, alternatives, and performance. No output schema exists, so the description fully compensates by detailing the return format and 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?

The description adds significant value beyond the schema: it explains depth enum meanings (quick=3, standard=5, thorough=8) and clarifies that the question parameter accepts broad/multi-part natural language. Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources. It explicitly contrasts with open-web search and sibling tools like ask_pipeworx, and provides specific examples of broad/multi-part queries it handles.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including alternatives for single lookups (ask_pipeworx) and breaking news (prefer ask_pipeworx). It also notes account requirements and depth tiers.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that it returns top-N relevant tools with full schemas, ready to call directly, which aligns with and enriches 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 informative but slightly verbose with many domain examples; however, the core purpose is front-loaded and every part adds value for the agent.

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

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

Given no output schema, the description adequately explains the return value and limit behavior, though pagination or error handling are not mentioned.

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 adds value by explaining query aliases and providing example natural language queries beyond the schema descriptions.

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

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

The description clearly states the tool finds tools by describing the data or task, and distinguishes itself from sibling tools by advising to call it FIRST to see the option set.

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 specifies when to use (browse, search, look up, discover) and advises calling it FIRST, but does not explicitly state when not to use it.

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

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

Discloses behavioral traits beyond annotations, including the USPTO PatentsView API sunset and soft-fall behavior, GDELT→GNews fallback, and the specific data fields returned. The description is consistent with the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, showing 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 reasonably concise given the amount of detail needed to explain a multi-source, fallback-heavy tool. It is front-loaded with examples and purpose, but the first sentence could be slightly more compact. However, every sentence adds necessary information.

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

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

Despite the complexity of the tool (multiple data sources, fallbacks, sunset dates) and the absence of an output schema, the description covers return fields, fallback mechanisms, and limitations comprehensively. No significant gaps remain for an agent to understand what the tool does and returns.

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 (type and value) with descriptions, achieving 100% schema coverage. The tool description reinforces and clarifies the expected formats (ticker or zero-padded CIK) and explicitly states that names are not supported, adding 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 starts with clear example queries and succinctly defines the tool's purpose: providing a full cross-source profile of a US public company in a single call. It specifies the sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and differentiates from sibling tools like resolve_entity, which handles name resolution.

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 advises to prefer this tool over chaining multiple single-source lookups for a holistic view, and clearly states that names are not supported—directing users to resolve_entity instead. This provides strong guidance on when and when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds 'clear sensitive data' context but does not significantly extend beyond annotations.

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

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

Two concise sentences, front-loaded with purpose and usage, no redundant information.

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

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

For a simple single-parameter destructive tool with comprehensive annotations, the description is fully complete and actionable.

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 already clearly describes the single parameter 'key'. The description adds no additional meaning.

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

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

The description clearly states the verb 'Delete' and resource 'memory', and explicitly distinguishes from siblings '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?

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and pairs with sibling tools for 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 provide readOnlyHint=true, idempotentHint=true, etc. Description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown format, and output is a text blob. This complements annotations 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?

Description is concise with two main sentences and a short bullet of use cases. It is front-loaded with the main purpose. Could be slightly tighter but no wasted words.

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

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

Given the simple tool with 2 params and rich annotations, the description adequately explains output format and usage. It does not cover edge cases like URL failures, but overall complete for the complexity level.

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

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

Input schema has 100% description coverage for both parameters (url with example, max_links with default and max). Description adds minimal extra meaning beyond schema (e.g., 'key links' but not max_links specifics). Baseline 3 is appropriate.

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

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

Description clearly states what the tool does: generate a production-ready llms.txt file for any URL. It specifies the action (generate), resource (llms.txt file), and target (any URL). It differentiates from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility scanning.

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

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

Description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. However, it lacks explicit when-not-to-use or alternatives among siblings, so it is clear but not exhaustive.

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 that it returns specific fields and defaults to active subscriptions, which is consistent and adds minor value but does not disclose additional behavioral traits beyond annotations.

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

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

The description is two sentences with no wasted words. It is front-loaded with the core purpose and supplemented with usage guidance, achieving maximum efficiency.

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 boolean parameter and no output schema, the description is complete. It states the action, scope, return fields, and usage context, leaving no 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 coverage is 100% with a clear description for the single parameter. The tool description does not add further meaning beyond referencing 'active subscriptions', so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and lists return fields. It is specific about the resource and action, but does not explicitly distinguish from sibling tools, though the context is clear.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear use cases and implies when to use vs. siblings like subscribe/unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns coordinates, but does not elaborate on other behavioral aspects like error handling or response format beyond what is implied.

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 concise (one sentence) and front-loaded with the verb 'Resolve'. However, it is slightly under-specified; a few extra words about the purpose of the coordinates could improve clarity without waste.

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

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

For a simple tool with one parameter and an output schema, the description is mostly complete. It states the core transformation (name to coords). The existence of an output schema reduces the need to describe return values, but the description could mention that coordinates are likely celestial.

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 0%, meaning the schema provides no explanation for the 'name' parameter. The description only implies the parameter is a target name, but lacks specifics about allowed formats, naming conventions, or examples beyond the schema's 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 'Resolve target name → coords.' clearly states the action (resolve), the input (target name), and the output (coords). It is specific and distinguishes from siblings like 'resolve_entity' by explicitly mentioning coordinates as the result.

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 like 'resolve_entity', 'cone_search', or 'compare_entities'. No exclusions, prerequisites, or context for selection are given.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover the safety profile. The description adds no behavioral context beyond these, but does not contradict them.

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

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

The description is a single concise sentence, front-loaded with the core purpose. However, it could benefit from slightly more explanatory content without being verbose.

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

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

Given the tool's complexity (nested criteria object, three parameters, output schema present), the description is too sparse. It does not explain what kinds of results are returned, how filtering behaves, or how to structure criteria 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 description coverage is 67%, and the description adds the phrase 'arbitrary criteria' aligning with the criteria parameter, but does not clarify the limit parameter's effect or add syntax details. The description provides minimal added value over 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 'Mission-scoped search with arbitrary criteria' clearly indicates the tool searches within a specific mission using flexible filtering, distinguishing it from tools like cone_search or search_within, though it doesn't specify the returned entity type (e.g., observations).

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 on when to use this tool versus alternatives such as cone_search or search_within, nor any exclusions or prerequisites provided.

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

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

Annotations are all false, providing minimal safety profile. The description adds significant behavioral context: rate limit (5 per identifier per day), free usage, no quota impact, and that the team reads digests daily. It does not contradict annotations. However, it does not describe any side effects beyond the obvious act of sending feedback, which is acceptable for a non-destructive tool.

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: it starts with the core purpose, then usage guidance, then behavioral notes, and ends with constraints. Each sentence adds value. While slightly longer than minimal, it remains focused and avoids redundancy. A minor improvement would be to tighten the phrasing, but it is already quite concise.

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

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

Given the tool's simplicity (no output schema, 3 parameters with 100% coverage), the description covers most aspects: purpose, usage, parameters, and behavioral constraints. However, it does not describe the return value or confirmation format, which would be helpful for an agent to know what to expect after invocation. A brief line like 'Returns a confirmation message' would improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining each parameter's meaning beyond the schema: it elaborates on the 'type' enum values, describes 'context' as optional and structured, and for 'message' specifies formatting guidelines ('Be specific', '1-2 sentences typical', '2000 chars max'). This aids the agent in constructing valid invocations.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb 'Tell' and the resource 'Pipeworx team', and distinguishes the tool by enumerating feedback types (bug, feature, data_gap, praise). No sibling tool covers feedback, so differentiation is inherent.

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 guidelines: when to use (bug, feature/data_gap, praise), what not to do ('don't paste the end-user's prompt'), and behavioral constraints (rate-limited to 5 per identifier per day, free, no quota impact). It also mentions the team reads digests daily, setting expectations for response.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching strategy (5min-1h), and that it's self-aggregating. 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?

Description is concise (three short paragraphs), front-loaded with the main purpose, and uses a clear bullet-like list for use cases. Every sentence adds value without redundancy.

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

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

Given the simple schema (one optional param), rich annotations, and no output schema, the description fully explains what is returned, data source, privacy, and caching. No gaps for a non-write tool.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds semantic context beyond the schema, explaining the trade-off between short and long windows ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description clearly states it returns top tools, top packs, and total call volume, specifying the resource (Pipeworx trending data) and the action (returns). It distinguishes itself from sibling tools like ask_pipeworx by focusing on aggregate trends rather than answering queries.

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

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

Explicitly lists three concrete use cases, providing clear guidance on when to use. However, it does not explicitly state when not to use or offer alternatives, though the sibling list implies specialization.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: algorithms, semantic anchor (Jaccard ≥0.30), partition filter, fill check against live order book, and conditions for not trading (realizable_edge ≤ 0). No contradictions with annotations.

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

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

The description is lengthy but front-loaded with purpose and modes. It is well-organized into paragraphs for each mode, though some details (e.g., Jaccard threshold, partition filter) are embedded in dense text. Slightly verbose but still efficient for the complexity.

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

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

Given the tool's complexity, no output schema, and need to explain algorithms, the description covers all aspects: modes, parameters, edge cases (placeholder slugs, low similarity), fill check, and references sibling tool. An AI agent can correctly invoke the tool and interpret its 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 description coverage is 100%. The description adds significant meaning: clarifies that event accepts slugs or full URLs, topic accepts seed questions, and explains how each parameter changes the tool's behavior. Provides examples and context 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 finds arbitrage opportunities on Polymarket via specific methods (monotonicity violations and partition-sum checks). It distinguishes between three modes: no args (trending scan), event (single-event partition check), and topic (cross-event scan), making the purpose precise and distinct from siblings.

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

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

Explicitly states when to use each mode: no args for a broad scan, event for a specific market, topic for cross-event patterns. Explains trade-offs (e.g., cross-event catches patterns single-event misses). Mentions sibling tool polymarket_fill_risk for custom sizing, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: caching at KV level, response structure, filter knobs, and exclusion of Fed bets from ranking. No contradiction.

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

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

Front-loads purpose well, but the description is verbose with detailed model family explanations and diagnostics, which could be trimmed for quicker scanning.

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

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

Given the complexity (9 params, no output schema), the description covers response structure, caching, diagnostic fields, and filtering knobs comprehensively, providing all necessary context 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 baseline is 3. The description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly vs min_kelly) and tradeable-edge knobs, going beyond the 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and distinguishes it from siblings by focusing on 'what should I bet on today' without paging hundreds of markets.

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 it (discovering opportunities where data diverges) and describes the model families and tradeable-edge knobs, but does not explicitly state when not to use it or compare to siblings like polymarket_arbitrage or bet_research.

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

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

The description adds significant behavioral details beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains the output structure (tracked, expired, snapshot_dates), how trend and decay_pp_per_day are computed, and data coverage gaps ('snapshots are written when polymarket_edges runs on a cache-miss'). No contradictions with annotations.

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

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

The description is long but well-structured. It front-loads the core purpose, then details the response fields. Every sentence adds value, though some phrases could be tightened (e.g., 'the latter is wide for a reason nobody is willing to take' is somewhat verbose). Still, it is clear and organized.

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

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

Given no output schema, the description thoroughly explains the return structure, including tracked[] with fields like edge_pp_net time-series, trend, decay_pp_per_day, expired[] with lifespan_days, and snapshot_dates[]. It also covers assumptions and limitations (TTL, snapshots). The tool's context is fully specified.

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 providing context for 'days' (lookback, default 14, max 30) and 'window' (snapshot family, default '1wk'), even though the schema already defines these. It explains how these parameters affect the output, which is helpful.

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' and answers a specific question: 'how long has this edge existed and is it shrinking?' The verb 'track' is implied, and the resource (polymarket edges) is identified. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on persistence over time.

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

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

The description explains when this tool is useful by contrasting a fresh wide edge with a 3-week-old one. It also notes limitations: history bounded by 60-day TTL and decay from daily closes, not intraday. While it doesn't explicitly list alternatives or when not to use, the context is clear enough.

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

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

The description is consistent with annotations (readOnlyHint, idempotentHint, etc.) and adds key behavioral details: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and warns about forced directional risk. It fully discloses the tool's non-destructive, read-only nature.

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 sized for the tool's complexity, with clear section headers (SINGLE-MARKET, BASKET) and no wasted sentences. It front-loads the critical information (requirement, purpose) and uses bold for emphasis.

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

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

Despite no output schema, the description fully explains all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, etc. for basket). It also covers edge cases like thin books, partial fills, and forced directional risk.

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

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

The input schema has 100% description coverage for all 4 parameters, but the description adds significant extra context: explains the mutual exclusivity of market vs event, the auto-detection of side in basket mode, and the interpretation of size_usd differently for buys/sells and basket mode. This goes well 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: checking realizable vs theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before them.

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

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

The description provides explicit when-to-use guidance: before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It also explains the required parameters (market or event) and default values, and warns about risks like partial basket fills converting arb into unhedged positions.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the two modes, response structure (leg prices, top_spreads_pp), and safety fields (compatibility_warning, temporal_alignment, skipped counts). It explains limitations like non-equivalent bet shapes and temporal gaps, fully disclosing behavior.

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

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

The description is dense with valuable information but slightly verbose. It is front-loaded with the core concept and uses clear sections. Every sentence contributes, but some redundancy could be tightened. Still highly effective.

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

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

Given the tool has 3 optional parameters and no output schema, the description compensates by explaining the response structure (leg prices, top spreads, safety fields) and edge cases (compatibility warnings, temporal alignment). It provides a complete mental model for a complex cross-venue spread tool.

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

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

Schema coverage is 100%, but the description adds significant context: it lists the 10 topic shortcuts, explains that explicit parameters override topics, and describes how each parameter is used (e.g., kalshi_event_ticker overrides the topic-mapped side). This adds meaning beyond the schema descriptions.

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

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

The description clearly defines the tool as computing cross-venue spreads between Kalshi and Polymarket for the same outcome. It specifies two modes (topic shortcuts and explicit event parameters) and distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description provides explicit when-to-use guidance (comparing same outcome across venues) and warns when not to rely on the tool, e.g., when compatibility_warning fires or temporal_alignment is false. It also cautions that most pre-mapped topics currently return warnings, setting realistic expectations.

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 provide readOnlyHint=true and idempotentHint=true; description adds scoping info and pairing guidance but no additional behavioral traits.

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 informative sentences, front-loaded with key actions. No redundancy or fluff.

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

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

Given low complexity (1 optional param, no output schema), description covers dual behavior, scoping, and related tools comprehensively.

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 includes description of 'key' parameter. Tool description adds context (scoping, purpose) beyond schema, improving usability.

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 tool retrieves a saved value or lists keys, with specific verb and resource. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly tells when to use (look up stored context) and mentions pairing with remember/forget. Offers alternative behavior (omit key to list all keys).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral details: polling safety, the effect of mark_read (flagging events read), and the alternative endpoint. However, there is a potential contradiction: mark_read modifies state (marks events read), which conflicts with readOnlyHint.

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

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

The description is two sentences plus a concise note about polling and an alternative endpoint. It is front-loaded with the main action and every sentence adds value, 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?

Despite no output schema, the description explains what the returned events contain (source, citation_uri, payload). It covers all key aspects: action, parameters, side-effects, and alternative access. It feels complete for a read-oriented tool with good annotations.

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

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

All 5 parameters have descriptions in the schema (100% coverage). The description adds extra context by explaining how to use type, since, and mark_read, and gives an example for type. This complements the schema without redundancy.

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 'Pull fired events from your subscription feed' and specifies the returned data (source, citation_uri, payload). It distinguishes this tool from siblings like 'list_subscriptions' by focusing on retrieving alerts rather than managing subscriptions.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read, and polling. It even offers an alternative (direct API endpoint). While it doesn't explicitly state when not to use, it gives sufficient guidance 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds fan-out behavior, failure fallbacks (GDELT→GNews), date acceptance formats, and return structure (changes[] grouped, total_changes, citations). 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?

Single paragraph front-loads purpose and examples, then concisely details sources, parameters, and return format. 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?

Despite no output schema, description specifies return structure (changes[] grouped by source, total_changes count, citation URIs). Covers multiple sources, fallback, date formats, and usage boundaries.

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

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

Schema covers 100% with descriptions, but description adds context: type only 'company', value ticker or CIK, and provides usage hint for since: 'Use "30d" or "1m" for typical monitoring.'

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

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

The description clearly states the tool provides a change feed for a company, with specific verb 'change feed' and examples like 'What's new with X'. It distinguishes from sibling tool entity_profile by contrasting dynamic vs static profile.

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

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

Explicitly tells when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' Also implies usage for monitoring changes over a window.

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

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

Annotations declare idempotentHint=true, destructiveHint=false. The description adds that memory is key-value scoped by identifier, with persistent storage for authenticated users and 24-hour retention for anonymous sessions. 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?

Three well-structured sentences that front-load the purpose, then provide usage guidance and behavioral details without redundancy.

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

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

Given the simplicity of the tool (2 params, no output schema), the description covers storage mechanism, scoping, persistence, and relationships with sibling tools, making it fully complete for agent usage.

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

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

Schema has 100% coverage with descriptions. The description adds value by providing naming conventions (e.g., 'subject_property') and clarifying that value can be any text, slightly enhancing 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: 'Save data the agent will need to reuse later.' It provides specific examples of what to store (resolved ticker, target address, etc.) and distinguishes itself from sibling tools recall and forget.

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: 'when you discover something worth carrying forward.' It also provides context on authentication scoping and session duration, and implicitly guides against overuse by pairing with recall and forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: internal cascading through multiple endpoints, auto-disambiguation for companies, and that it replaces 2-3 manual lookups. 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 compact and informative, starting with example queries to set context. Every sentence adds value, though breaking into bullet points could improve readability. No filler or repetition.

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 lacking an output schema, the description fully explains return values for both types, including citation URIs and disambiguation behavior. It covers the tool's internal cascading and efficiency benefit. For a tool with two distinct use cases, this is complete and sufficient for correct 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?

Schema coverage is 100%, so baseline is 3. The description significantly enriches both parameters: for 'type', it explains the two options and their respective outputs; for 'value', it provides concrete examples and mentions auto-disambiguation for company names. This adds substantial 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 defines the tool's purpose: resolve a user-provided name to a canonical/official identifier. It includes specific example queries, distinguishes between supported types (company and drug), and explicitly contrasts with sibling tools by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and example queries that trigger usage. However, it does not explicitly list when not to use or mention alternative tools like 'lookup_name' for cases where a canonical ID is not needed.

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

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

The description adds behavioral details beyond the annotations: it explains the probing mechanism (uses ai_visibility_check per entity), the ranking by score, and the output fields (score, confidence, signal density). Annotations already indicate safe, read-only, idempotent behavior. No contradictions.

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

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

The description is concise and well-structured: two sentences with front-loaded purpose. The first sentence states the core function, the second adds behavioral detail and a concrete use case example. No redundant or unnecessary words.

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

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

Given the tool's complexity (4 parameters, no output schema, high schema coverage), the description provides sufficient context: it explains the probing mechanism, output fields, and typical use case. It lacks detailed return format but mentions key output fields, which is adequate for an agent to understand expected results.

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

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

The input schema has 100% coverage with descriptions for all parameters. The tool description adds extra meaning: it explains that the first entity is treated as the 'subject' for narrative, and the rest as competitors, which is not in the schema. This enriches the semantic understanding 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 purpose: 'Compare AI visibility across multiple entities side-by-side'. It specifies the action (compare), the resource (AI visibility), and the scope (multiple entities), distinguishing it from the sibling tool ai_visibility_check which handles single entities.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and explicitly mentions that it probes each entity with ai_visibility_check, implying the alternative for single entities. However, it does not explicitly state when not to use this tool or provide direct alternatives beyond the mention of ai_visibility_check.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description discloses key behaviors: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed lists timeouts. It also outlines the return structure including summary fields, advisories, links, and alternative versions.

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 information and front-loads the purpose. While longer than ideal, every sentence contributes value (usage, return fields, limitations, failure behavior). Minor redundancy in repeating default behavior but overall efficient.

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

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

Given the complexity (aggregating two external services) and lack of output schema, the description covers essential aspects: return fields, ecosystem limitation, timeout behavior, and partial failure mode. Minor gaps: error handling for invalid package names or network failures beyond timeouts, and whether version ranges are supported (assumed exact version only).

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 both parameters documented. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted for the 'package' parameter, which is not in the schema. The description also rephrases the default behavior for 'version'.

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

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

The description clearly states the composite purpose: checking whether to add an npm package by aggregating data from deps.dev and bundlephobia. It distinguishes itself from potential sibling tools by explicitly limiting scope to the npm ecosystem in v1 and mentioning alternatives for other ecosystems.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives a when-not-to-use: for other package ecosystems, use deps.dev:version directly.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds detailed behavioral traits: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation noted, and returns offsets and scores. 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 concise (under 100 words), front-loaded with the key verb and resource, and every sentence adds value without fluff. Well-structured.

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

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

Despite no output schema, the description covers behavioral details (embedding model, window size, truncation), usage pairing, and return format (passages with offsets and scores). Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so all parameters are already described. The description adds minimal new detail beyond schema (e.g., context about text being from a fetched record). Baseline of 3 is appropriate; description doesn't significantly enhance parameter understanding.

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

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

The description clearly states the verb 'search' and the resource 'inside a fetched record', specifying it's semantic search. It distinguishes from siblings like ask_pipeworx_grounded by explaining how they pair, 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?

Explicitly states when to use: 'when the record is too big to cram into the prompt'. It also describes how it pairs with ask_pipeworx_grounded, effectively guiding the agent on alternatives and 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?

Discloses behavioral traits beyond annotations: OAuth requirement, type-specific examples, delivery channel limits (SMS cap, webhook auto-disable), and one-time webhook secret. Annotations already indicate idempotent and non-destructive, but description adds valuable 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?

Description is well-structured and front-loaded with core purpose, but slightly long; each sentence adds value. Efficient for the complexity.

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

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

Covers requirements, type parameters, delivery channels, and limits. Lacks explicit error handling or return format details beyond 'new subscription id', but is adequately complete given the presence of schema and annotation context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant meaning with type-specific examples, delivery nuances (phone verification, webhook secret), and constraints, raising the score to 4.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context on when to use (requires OAuth account) and includes type-specific parameters, but does not explicitly mention alternatives or 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about being an onboarding entry point, returning categorized questions, and supporting topic filtering, which is valuable beyond annotations.

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

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

The description is moderately long but well-structured with clear sentences, front-loading triggers and then behavior. It could be slightly tighter, but it efficiently conveys all necessary information.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description is complete. It explains the return format, usage context, and parameter behavior, leaving no 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 coverage is 100% for the single optional parameter. The description adds meaning by listing allowed values and explaining behavior when omitted, providing clarity beyond the schema's 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 clearly states the tool returns example questions and how to answer them using Pipeworx tools. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself as the onboarding entry point, setting it apart 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 says when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It mentions related meta-tools but does not explicitly state when not to use it, though context is clear.

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

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

Beyond annotations (idempotent, not destructive), the description adds ownership enforcement, row deactivation instead of deletion, and the availability of historical events via recent_alerts. This provides valuable behavioral insight.

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

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

Two concise sentences, front-loaded with the action. Every sentence adds value without redundancy. Efficient and clear.

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

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

The description covers the tool's effect, ownership rule, and side effect on historical data. Given the low complexity and absence of output schema, it is sufficiently complete. A minor gap is the lack of return value hint, but overall adequate.

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

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

The input schema fully describes the id parameter as a uuid from subscribe, with 100% coverage. The description adds no additional semantics beyond what the schema already provides, so it meets the baseline but does not exceed it.

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 'Cancel a subscription by id,' specifying the action and resource. It distinguishes from siblings like subscribe and list_subscriptions by being the only tool that performs cancellation.

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

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

The description provides usage context: ownership enforcement ('you can only cancel your own subscriptions') and behavioral distinction from deletion. It implies when to use (cancel but keep history) but does not explicitly state when not to use or mention 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 readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral context: return verdict types, structured form, actual value with citation, percent delta, and replaces 4–6 sequential calls. 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?

Front-loaded with natural-language examples, then explains usage and scope. Every sentence adds value with no redundancy or fluff. Slightly verbose with multiple examples, but overall efficient for the tool's complexity.

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

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

Given a single parameter, no output schema, and comprehensive annotations, the description fully covers what the tool does, when to use it, what it returns, and its scope. No missing information for an AI to correctly select and invoke the tool.

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

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

Schema description coverage is 100% for the single parameter 'claim' with good examples. Description reinforces the parameter's purpose and adds context about supported claim types (company-financial), but does not significantly extend beyond 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?

Clearly states the tool validates natural-language factual claims using authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. Distinguishes from sibling tools by explicitly positioning it as a replacement for multiple sequential calls, making its unique value clear.

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: 'whenever the agent needs to check whether something a user said is factually correct.' Also specifies scope (company-financial claims) and examples. Does not explicitly exclude other claim types or mention alternative tools, but the scope restriction provides implicit guidance.

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